Project Structure

Serko Northsky is organized as a monorepo using PNPM workspaces for Node.js packages and Poetry for Python dependencies. This structure enables code sharing, consistent tooling, and streamlined development across all applications.

Directory Overview

serko-northsky/
├── apps/                     # Application workspaces
│   ├── backend/              # FastAPI backend (Python)
│   ├── frontend/             # Next.js frontend (React/TypeScript)
│   ├── tools/                # Internal tools app (React/TypeScript)
│   └── docs/                 # Docusaurus documentation site
├── packages/                 # Shared code packages
│   └── shared/               # Shared utilities and types
├── infra/                    # Infrastructure as Code
│   ├── pulumi/               # Pulumi IaC (TypeScript)
│   └── k8s/                  # Kubernetes Helm charts
├── scripts/                  # Root-level utility scripts
├── hooks/                    # Git hooks
├── .github/                  # GitHub Actions CI/CD workflows
├── docker-compose.yml        # Local development environment
├── pnpm-workspace.yaml       # PNPM monorepo configuration
├── package.json              # Root package configuration
└── pyproject.toml            # Python project configuration

Applications

Backend (apps/backend)

The Python FastAPI backend serves as the API layer for the platform.

Aspect	Details
Language	Python 3.13+
Framework	FastAPI
Database	AlloyDB (PostgreSQL) via SQLAlchemy
Dev Port	8000

Key directories:

• src/ — Main application source code
• tests/ — Test suite (pytest)
• scripts/ — Database and utility scripts

Commands:

pnpm dev:backend          # Start development server
pnpm test                 # Run tests
pnpm lint:backend         # Run linting

---

Frontend (apps/frontend)

The main user-facing web application built with Next.js.

Aspect	Details
Language	TypeScript
Framework	Next.js 16, React 19
Styling	Tailwind CSS v4
Auth	Firebase
Dev Port	3000

Key features:

• OpenAPI client auto-generated from backend schema
• Internationalization (i18n) support
• TypeScript strict mode

Commands:

pnpm dev:frontend         # Start development server
pnpm build:frontend       # Production build
pnpm lint:frontend        # Run linting

---

Tools (apps/tools)

Internal tools and utilities application for administration and monitoring.

Aspect	Details
Language	TypeScript
Framework	Next.js 16, React 19
Monitoring	Langfuse integration
Dev Port	3001

Commands:

pnpm dev:tools            # Start development server

---

Documentation (apps/docs)

This documentation site, built with Docusaurus.

Aspect	Details
Framework	Docusaurus 3.7
Features	Mermaid diagrams, MDX support
Dev Port	3002

Commands:

pnpm dev:docs             # Start development server
pnpm build:docs           # Production build

Shared Packages

Shared (packages/shared)

Contains shared utilities, types, and constants used across applications.

// Example: importing from shared package
import { someUtility } from '@serko-northsky/shared';

Infrastructure

Pulumi (infra/pulumi)

Infrastructure as Code using Pulumi with TypeScript.

Key directories:

• src/gcp/ — GCP resource modules (AlloyDB, GKE, networking, etc.)
• scripts/ — Automation scripts
• Pulumi.*.yaml — Environment-specific configurations

Environments: dev, test, prod

Kubernetes (infra/k8s)

Helm charts for deploying applications to GKE.

Key files:

• helm/serko-northsky/ — Main Helm chart
• values/ — Environment-specific values

Configuration Files

Package Management

File	Purpose
pnpm-workspace.yaml	Defines PNPM workspaces (apps/*, packages/*)
package.json	Root scripts and dependencies
pnpm-lock.yaml	Node.js dependency lock file
pyproject.toml	Python project configuration (Poetry)
poetry.lock	Python dependency lock file

Development

File	Purpose
docker-compose.yml	Local development environment
.pre-commit-config.yaml	Pre-commit hooks for code quality
.env.example	Environment variables template

CI/CD

Directory	Purpose
.github/workflows/	GitHub Actions workflow definitions

Common Commands

Run these commands from the repository root:

# Development
pnpm dev                  # Start frontend + backend
pnpm dev:frontend         # Frontend only
pnpm dev:backend          # Backend only
pnpm dev:docs             # Documentation site

# Build
pnpm build                # Build all applications
pnpm build:frontend       # Frontend only
pnpm build:backend        # Backend only

# Testing & Quality
pnpm test                 # Run all tests
pnpm lint                 # Run linting
pnpm type-check           # TypeScript type checking

# Database
pnpm db:migrate           # Create migration
pnpm db:upgrade           # Run migrations

# API Client
pnpm openapi:generate-client    # Generate frontend API client

# Docker
pnpm docker:build         # Build all images
pnpm docker:up            # Start containers
pnpm docker:down          # Stop containers

Dependency Graph

Adding New Packages

To add a new shared package:

1. Create the package directory:

   mkdir -p packages/my-package/src

2. Add a package.json:

   {
     "name": "@serko-northsky/my-package",
     "version": "0.0.0",
     "main": "dist/index.js",
     "types": "dist/index.d.ts"
   }

3. The package is automatically included in the workspace via pnpm-workspace.yaml.

Next Steps

• Installation — Set up your development environment
• Configuration — Configure environment variables
• Architecture — Deep dive into the backend architecture