gridpilot.gg/plans/2025-12-15_clean-architecture-migration-plan.md

# 2025-12-15 Clean Architecture Migration Plan for GridPilot

## 1. Current State Summary

- **Core**: Modular structure with domains (`analytics`, `automation`, `identity`, `media`, `notifications`, `racing`, `social`, `shared`). Contains pure domain elements (`entities`, `value-objects`, `repositories` interfaces, `use-cases`, `ports`). Violations: Infrastructure leaks (`infrastructure/repositories/InMemory*` in `analytics`, `automation`), adapters in `automation/infrastructure/adapters`.
- **Apps/API**: NestJS app with internal layers (`application/services`, `infrastructure/database`, `presentation/controllers`). Mostly placeholder (`hello.service`, `analytics.controller`). [`apps/api/src/infrastructure/database/database.module.ts`](apps/api/src/infrastructure/database/database.module.ts) suggests persistence setup but minimal implementation.
- **Apps/Website**: `lib/` holds DI (`di-container.ts`, `di-tokens.ts`), auth (`InMemoryAuthService.ts`), presenters (40+ `presenters/*.ts` – business logic mixed with presentation), utils. Presenters likely contain domain logic violating isolation.
- **Apps/Companion**: DI setup (`di-container.ts`), IPC handlers, renderer components.
- **Testing**: Comprehensive `/tests/` (`unit/`, `integration/`, `e2e/`, `smoke/`, `bdd/`) testing domains/use-cases. `/testing-support/` with fakers, demo adapters – partial match but not structured as `/testing/factories/fakes/fixtures/helpers`.
- **Persistence**: Sparse; no ORM entities, migrations, or real repos visible. In-memory only in core.
- **Overall**: Partial Clean Arch adoption in core domains; infra/UI mixing; no top-level `/adapters`; testing scattered.

## 2. Gap Analysis per Layer/Domain

### Core (Business Rules)
- **Compliant**: Domain entities/VO/services/use-cases/ports in `core/*/domain|application`.
- **Violations**: Infra in core (`InMemory repos`, adapters). Must extract to `/adapters`.
- **Domains**: `analytics` (page views), `automation` (racing wizards), `media` (avatars), `notifications`, `racing` (leagues/races), `social` – all need infra purge.

### Adapters (Details)
- **Gap**: No `/adapters/` top-level. Persistence (typeorm/inmemory), auth/media/notifications/logging missing structure.
- **Action**: Move core infra; implement mappers, ORM entities, real repos.

### Apps (Delivery)
- **Backend (API)**: Internal layers ok as composition root but move domain deps to core refs.
- **Frontend (Website/Companion)**: Presenters/DI in `lib/` – extract business to core use-cases, keep UI presenters thin.
- **Violations**: Domain logic in presenters (`LeagueStandingsPresenter.ts` etc.).

### Testing
- **Gap**: `/tests/unit/domain/` mixes support/cases. `/testing-support/` unstructured.
- **Action**: Pure cases in `/tests`, support to `/testing/factories` etc. No DTOs in domain tests.

### Persistence/Bootstrap
- **Gap**: No `/adapters/persistence/migrations`, `/adapters/bootstrap`. Database.module placeholder.

## 3. Phased Migration Plan

Focus: Backend/core first (Phases 1-7), then frontend (8-10), testing (11), verification (12).

### Phase 1: Directory Setup & Skeleton
- **Scope**: Create dirs: `/adapters/persistence/{typeorm,inmemory}`, `/adapters/{auth,media,notifications,logging}`, `/adapters/bootstrap`, `/testing/{fixtures,factories,fakes,helpers}`, `/adapters/persistence/migrations`.
- **Focus**: Backend structure.
- **Prerequisites**: None.
- **Outcome**: Empty skeleton matching target.
- **Risks**: Path conflicts (low).

### Phase 2: Purge Core Infrastructure – In-Memory Repos
- **Scope**: Move `core/*/infrastructure/repositories/InMemory*` → `/adapters/persistence/inmemory/*/InMemory*.ts`. Delete source dirs. Update core imports to ports only.
- **Focus**: Core purity (analytics, automation).
- **Prerequisites**: Phase 1.
- **Outcome**: Core interfaces-only repos.
- **Risks**: Import breaks in tests/use-cases.

### Phase 3: Extract Automation Adapters
- **Scope**: Move `core/automation/infrastructure/adapters/*` → `/adapters/*` (e.g., logging → `/adapters/logging`). Update paths.
- **Focus**: Backend adapters.
- **Prerequisites**: Phase 2.
- **Outcome**: Centralized adapters.
- **Risks**: DI token mismatches.

### Phase 4: Implement Persistence Mappers & ORM Skeleton
- **Scope**: Create `/adapters/persistence/typeorm/*/OrmEntity.ts`, `Mapper.ts` for key domains (racing League/Race, analytics PageView). Stub repos.
- **Focus**: Backend persistence.
- **Prerequisites**: Phase 1-3.
- **Outcome**: ORM ready for data migration.
- **Risks**: Schema design errors.

### Phase 5: Migrate API Layers to Core Dependencies
- **Scope**: Refactor `apps/api/src/application/*`, `presentation/*` to use core use-cases/ports. Move `infrastructure/database/*` → `/adapters/persistence/typeorm`.
- **Focus**: Backend API.
- **Prerequisites**: Phase 4.
- **Outcome**: API as thin delivery.
- **Risks**: Controller logic loss.

### Phase 6: Add Migrations & Bootstrap
- **Scope**: Create `/adapters/persistence/migrations/*.ts` for schema. `/adapters/bootstrap/EnsureInitialData.ts` using use-cases.
- **Focus**: Backend operability.
- **Prerequisites**: Phase 4.
- **Outcome**: Schema + bootstrap.
- **Risks**: Data loss on migrate.

### Phase 7: Core Domain Refinements
- **Scope**: Enforce entities immutable/private ctor/factory methods across domains. Add domain events if missing.
- **Focus**: Backend core.
- **Prerequisites**: Phase 1-6.
- **Outcome**: Strict domain.
- **Risks**: Breaking changes in use-cases.

### Phase 8: Refactor Website Presenters
- **Scope**: Extract business logic from `apps/website/lib/presenters/*` to core use cases/domain services; keep thin presenters in `apps/website/lib/presenters` as UI adapters implementing core output ports.
- **Focus**: Frontend/backend split.
- **Prerequisites**: Phase 7.
- **Outcome**: Business logic extracted to core; thin UI presenters remain in app.
- **Risks**: UI logic entanglement.
- **Presenter Note**: Core defines presenter interfaces (output ports) if needed; implementations (adapters) stay in apps/website.

### Phase 9: Clean Frontend DI & Auth
- **Scope**: Remove `apps/website/lib/{di-*,auth/*}` or thin to delivery. Use core ports.
- **Focus**: Frontend.
- **Prerequisites**: Phase 8.
- **Outcome**: Apps pure delivery.
- **Risks**: Auth breakage.

### Phase 10: Companion Alignment
- **Scope**: Align `apps/companion/{main/renderer/lib}` to use core/adapters. Extract any domain.
- **Focus**: Frontend.
- **Prerequisites**: Phase 9.
- **Outcome**: Consistent delivery.
- **Risks**: Electron IPC changes.

### Phase 11: Testing Restructure
- **Scope**: Move test support to `/testing/factories/*Factory.ts`, `fakes/*Fake.ts`. Pure cases in `/tests`. Enforce no DTOs in domain tests.
- **Focus**: Testing.
- **Prerequisites**: All prior.
- **Outcome**: Strict testing.
- **Risks**: Test failures.

### Phase 12: Verification & Enforcement
- **Scope**: Add ESLint/dependency-cruiser rules for layers. Run full test suite, e2e.
- **Focus**: All.
- **Prerequisites**: Phase 11.
- **Outcome**: Enforced architecture.
- **Risks**: Rule false positives.

```mermaid
graph TD
    A[Phase 1: Dirs] --> B[Phase 2: Core Purge]
    B --> C[Phase 3: Adapters]
    C --> D[Phase 4: ORM]
    D --> E[Phase 5: API]
    E --> F[Phase 6: Migrate/Bootstrap]
    F --> G[Phase 7: Domain Refine]
    G --> H[Phase 8: Refactor Website Presenters]
    H --> I[Phase 9: Frontend Clean]
    I --> J[Phase 10: Companion]
    J --> K[Phase 11: Testing]
    K --> L[Phase 12: Verify]
```

## 4. TODO Checklist

- [ ] Phase 1: Directory Setup & Core Skeleton
- [ ] Phase 2: Purge Core Infrastructure – In-Memory Repos
- [ ] Phase 3: Extract Automation Adapters
- [ ] Phase 4: Implement Persistence Mappers & ORM Skeleton
- [ ] Phase 5: Migrate API Layers to Core Dependencies
- [ ] Phase 6: Add Migrations & Bootstrap
- [ ] Phase 7: Core Domain Refinements
- [ ] Phase 8: Refactor Website Presenters (logic to core use cases; thin adapters in app)
- [ ] Phase 9: Clean Frontend DI & Auth
- [ ] Phase 10: Companion Alignment
- [ ] Phase 11: Testing Restructure
- [ ] Phase 12: Verification & Enforcement