Handelsregister App

Appearance

Mono-Repo Architecture ​

Architecture Decision: Single Repository, Multiple Services ​

Single repository, multiple services approach for coordinated development across TypeScript frontend and Python workers with shared database schema.

Repository Structure ​

handelsregister-app/
├── apps/
│   ├── web/                    # SvelteKit frontend + API routes
│   │   ├── Dockerfile          # Production container definition
│   │   └── src/
│   ├── workers/                # Python background processors  
│   │   ├── Dockerfile          # Production container definition
│   │   └── src/
│   └── docs/                   # VitePress documentation
├── supabase/                   # Database migrations & RPC functions
│   ├── Dockerfile              # Migration runner container
│   └── migrations/
├── packages/
│   ├── shared-types-ts/       # Generated TypeScript types
│   └── shared-types-py/       # Generated Python Pydantic models
├── scripts/
│   └── seed-with-users.js     # Seed local supabase instance
├── docker-compose.dev.yml     # Optional local development
└── package.json               # Root workspace configuration

Development vs Production Workflow ​

Development (Native) ​

  • Frontend: cd apps/web && npm run dev
  • Workers: cd apps/workers && python src/main.py
  • Database: Local Supabase or development branch
  • No Docker - faster iteration, better debugging

Production (Containerized) ​

  • Coolify reads Dockerfiles from each app directory
  • Builds containers on server with exact environment specifications
  • Deploys multiple services from single Git push
  • Shared environment variables across all services

Key Principles ​

Coordinated Deployments ​

  • Atomic updates: Database migrations, workers, and frontend deploy together
  • Dependency management: Migration service runs before application services
  • Shared configuration: Environment variables managed at project level
  • Rollback safety: All services can be reverted to previous version

Service Communication via Database ​

  • No direct inter-service communication between frontend and workers
  • Database as message broker through job queue tables
  • RPC functions bridge frontend to processing pipeline
  • Independent scaling of each service type

Team Workflow ​

Branch Strategy ​

  • Local development: Native tools (npm, python)
  • Feature branches: Supabase branches for database testing
  • Integration testing: Docker compose for full-stack testing (optional)
  • Production: Automated deployment from main branch

Collaboration Benefits ​

  • Atomic feature development - database, backend, frontend in single PR
  • Type safety across stack - shared types prevent integration errors
  • Complete context - developers see impact across all services
  • Simplified onboarding - single repository to clone and understand

This mono-repo architecture optimizes for team coordination and deployment simplicity while maintaining the flexibility to scale individual services independently.