gridpilot.gg/docs/architecture/shared/FILE_STRUCTURE.md

File Structure

Core

core/                                  # * Business- & Anwendungslogik (framework-frei)
├── shared/                            # * Gemeinsame Core-Bausteine
│   ├── domain/                        # * Domain-Basistypen
│   │   ├── Entity.ts                  # * Basisklasse für Entities
│   │   ├── ValueObject.ts             # * Basisklasse für Value Objects
│   │   └── DomainError.ts             # * Domain-spezifische Fehler
│   └── application/
│       └── ApplicationError.ts        # * Use-Case-/Application-Fehler
│
├── racing/                            # * Beispiel-Domain (Bounded Context)
│   ├── domain/                        # * Fachliche Wahrheit
│   │   ├── entities/                  # * Aggregate Roots & Entities
│   │   │   ├── League.ts              # * Aggregate Root
│   │   │   └── Race.ts                # * Entity
│   │   ├── value-objects/             # * Unveränderliche Fachwerte
│   │   │   └── LeagueName.ts           # * Beispiel VO
│   │   ├── services/                  # * Domain Services (Regeln, kein Ablauf)
│   │   │   └── ChampionshipScoringService.ts  # * Regel über mehrere Entities
│   │   └── errors/                    # * Domain-Invariantenfehler
│   │       └── RacingDomainError.ts
│   │
│   └── application/                   # * Anwendungslogik
│       ├── ports/                     # * EINZIGE Schnittstellen des Cores
│       │   ├── input/                 # * Input Ports (Use-Case-Grenzen)
│       │   │   └── CreateLeagueInputPort.ts
│       │   └── output/                # * Output Ports (Use-Case-Ergebnisse)
│       │       └── CreateLeagueOutputPort.ts
│       │
│       ├── use-cases/                 # * Einzelne Business-Intents
│       │   └── CreateLeagueUseCase.ts
│       │
│       └── services/                  # * Application Services (Orchestrierung)
│           └── LeagueSetupService.ts  # * Koordiniert mehrere Use Cases

Adapters

adapters/                              # * Alle äußeren Implementierungen
├── persistence/                       # * Datenhaltung
│   ├── typeorm/                       #   Konkrete DB-Technologie
│   │   ├── entities/                  #   ORM-Entities (nicht Domain!)
│   │   └── repositories/              # * Implementieren Core-Ports
│   │       └── LeagueRepository.ts
│   └── inmemory/                      #   Test-/Dev-Implementierungen
│       └── LeagueRepository.ts
│
├── notifications/                     #   Externe Systeme
│   └── EmailNotificationAdapter.ts    #   Implementiert Notification-Port
│
├── logging/                           #   Logging / Telemetrie
│   └── ConsoleLoggerAdapter.ts        #   Adapter für Logger-Port
│
└── bootstrap/                         #   Initialisierung / Seeding
    └── EnsureInitialData.ts           #   App-Start-Logik

API

apps/api/                              # * Delivery Layer (HTTP)
├── app.module.ts                      # * Framework-Zusammenbau
│
├── leagues/                           # * Feature-Modul
│   ├── LeagueController.ts            # * HTTP → Application Service
│   │
│   ├── dto/                           # * Transport-DTOs (HTTP)
│   │   ├── CreateLeagueRequestDto.ts  # * Request-Shape
│   │   └── CreateLeagueResponseDto.ts # * Response-Shape
│   │
│   └── presenters/                   # * Output-Port-Adapter
│       └── CreateLeaguePresenter.ts   # * Core Output → HTTP Response
│
└── shared/                            #   API-spezifisch
    └── filters/                      #   Exception-Handling

Frontend

apps/website/                          # * Frontend (UI)
├── app/                               # * Next.js Routen
│   └── leagues/                       # * Page-Level
│       └── page.tsx
│
├── components/                        # * Reine UI-Komponenten
│   └── LeagueForm.tsx
│
├── lib/
│   ├── api/                           # * HTTP-Client
│   │   └── LeaguesApiClient.ts        # * Gibt NUR API DTOs zurück
│   │
│   ├── dtos/                          # * API-Vertrags-Typen
│   │   └── CreateLeagueResponseDto.ts
│   │
│   ├── commands/                     # * Command Models (Form State)
│   │   └── CreateLeagueCommandModel.ts
│   │
│   ├── presenters/                   # * DTO → ViewModel Mapper
│   │   └── CreateLeaguePresenter.ts
│   │
│   ├── view-models/                  # * UI-State
│   │   └── CreateLeagueViewModel.ts
│   │
│   ├── services/                     # * Frontend-Orchestrierung
│   │   └── LeagueService.ts
│   │
│   └── blockers/                     #   UX-Schutz (Throttle, Submit)
│       ├── SubmitBlocker.ts
│       └── ThrottleBlocker.ts