Adds requirements and userstories. also updates diagrams to be mermaid diagrams instead of text variants

2026-06-17 11:31:17 +02:00
parent 73025c5a84
commit c7154e288f
13 changed files with 1018 additions and 163 deletions
@@ -8,54 +8,39 @@ The frontend is a React SPA (to be built) that communicates with the API via RES

 ## Architecture Diagram

-```
-+--------------------------------------------------+
-|              Client Layer                        |
-|  +--------------------------------------------+ |
-|  |   React SPA (SlpModularCms.Frontend)       | |
-|  |   Vite + React Router v7 + shadcn/ui       | |
-|  |   Tailwind CSS v4 (#ac0000 theme)          | |
-|  +--------------------------------------------+ |
-+---------------------------+----------------------+
-                            | HTTP REST / JSON
-+---------------------------v----------------------+
-|              API Layer                           |
-|  +--------------------------------------------+ |
-|  |       SlpModularCms.Api (ASP.NET Core)     | |
-|  |   - JWT Bearer Auth Middleware             | |
-|  |   - CORS, Swagger/OpenAPI                  | |
-|  |   - Module registration pipeline          | |
-|  +--------------------------------------------+ |
-|                                                  |
-|  +------------------+  +---------------------+  |
-|  |  Identity Module |  | Availability Module |  |
-|  |  - AuthController|  | - AvailabilityCtrl  |  |
-|  |  - SetupCtrl     |  | - PersistentService |  |
-|  |  - UsersCtrl     |  | - CircuitBreaker    |  |
-|  +------------------+  +---------------------+  |
-+---------------------------+----------------------+
-                            |
-+---------------------------v----------------------+
-|              Core Layer                          |
-|  +--------------------------------------------+ |
-|  |          SlpModularCms.Core                | |
-|  |  - ApplicationDbContext (EF Core)          | |
-|  |  - Domain Entities                         | |
-|  |  - Identity Services (Auth, Setup, Invite) | |
-|  |  - IModule interface + ModuleInfo          | |
-|  +--------------------------------------------+ |
-+---------------------------+----------------------+
-                            |
-+---------------------------v----------------------+
-|              Data Layer                          |
-|  +--------------------------------------------+ |
-|  |         SQL Server Database                | |
-|  |  - ASP.NET Identity tables                 | |
-|  |  - RefreshTokens                           | |
-|  |  - Invitations                             | |
-|  |  - GlobalAvailabilityState                 | |
-|  +--------------------------------------------+ |
-+--------------------------------------------------+
+```mermaid
+graph TD
+    subgraph ClientLayer["Client Layer"]
+        Frontend["React SPA\nVite + TanStack Router + shadcn/ui\nTailwind CSS v4 #ac0000"]
+    end
+
+    subgraph ApiLayer["API Layer"]
+        Api["SlpModularCms.Api\nASP.NET Core\nJWT Bearer, CORS, Swagger"]
+        Identity["Identity Module\nAuthController\nSetupController\nUsersController"]
+        Avail["Availability Module\nAvailabilityController\nPersistentService + CircuitBreaker"]
+    end
+
+    subgraph CoreLayer["Core Layer"]
+        Core["SlpModularCms.Core\nApplicationDbContext\nDomain Entities\nIdentity Services\nIModule interface"]
+    end
+
+    subgraph DataLayer["Data Layer"]
+        DB[("SQL Server\nIdentity tables\nRefreshTokens\nInvitations\nGlobalAvailabilityState")]
+    end
+
+    Frontend -->|HTTP REST / JSON| Api
+    Api --> Identity
+    Api --> Avail
+    Identity --> Core
+    Avail --> Core
+    Core --> DB
+
+    style Frontend fill:#2196F3,stroke:#0D47A1,color:#fff
+    style Api fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style Identity fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style Avail fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style Core fill:#FFC107,stroke:#F57F17,color:#000
+    style DB fill:#FF5722,stroke:#BF360C,color:#fff
 ```

 ## Component Descriptions
@@ -92,24 +77,36 @@ The frontend is a React SPA (to be built) that communicates with the API via RES

 ## Data Flow

-```
-Login Flow:
-  Browser -> POST /auth/login -> AuthController
-          -> AuthService.AuthenticateAsync()
-          -> PasswordHasher validates credentials
-          -> JwtService generates access + refresh tokens
-          -> Returns {accessToken, refreshToken}
+```mermaid
+sequenceDiagram
+    participant Browser
+    participant AuthController
+    participant AuthService
+    participant DB

-Invite Flow:
-  Admin -> POST /users/invite -> UsersController
-        -> InvitationService.CreateInvitationAsync()
-        -> Stores Invitation entity with token
-        -> Returns invite link
+    Note over Browser,DB: Login Flow
+    Browser->>AuthController: POST /auth/login
+    AuthController->>AuthService: AuthenticateAsync()
+    AuthService->>DB: Validate credentials
+    DB-->>AuthService: User found
+    AuthService-->>AuthController: access + refresh tokens
+    AuthController-->>Browser: 200 OK with tokens

-New User Setup:
-  User -> POST /users/complete-setup -> UsersController
-       -> InvitationService.CompleteInvitationAsync()
-       -> Sets password, activates account
+    Note over Browser,DB: Invite Flow
+    Browser->>AuthController: POST /users/invite
+    AuthController->>AuthService: CreateInvitationAsync()
+    AuthService->>DB: Store Invitation entity
+    DB-->>AuthService: Stored
+    AuthService-->>AuthController: invite token
+    AuthController-->>Browser: 200 OK with invite link
+
+    Note over Browser,DB: New User Setup
+    Browser->>AuthController: POST /users/complete-setup
+    AuthController->>AuthService: CompleteInvitationAsync()
+    AuthService->>DB: Set password, activate account
+    DB-->>AuthService: Updated
+    AuthService-->>AuthController: success
+    AuthController-->>Browser: 200 OK
 ```

 ## Integration Points
@@ -2,26 +2,28 @@

 ## Business Context Diagram

-```
-+--------------------------------------------------+
-|            SlpModularCms Platform                |
-|                                                  |
-|  +-----------+   +-----------+   +-----------+  |
-|  | Identity  |   |   CMS     |   |Availability|  |
-|  |  Module   |   |  Module   |   |  Module   |  |
-|  | (Auth +   |   | (Content  |   | (System   |  |
-|  |  Users)   |   | Mgmt)     |   |  Status)  |  |
-|  +-----------+   +-----------+   +-----------+  |
-|                                                  |
-|  +-------------------------------------------+  |
-|  |              Core / Shell                 |  |
-|  |  (Domain entities, DbContext, Module I/F) |  |
-|  +-------------------------------------------+  |
-+--------------------------------------------------+
-         |                           |
-         v                           v
-  [Admin Frontend]           [External Clients]
-  (React SPA)                (API consumers)
+```mermaid
+graph TD
+    subgraph Platform["SlpModularCms Platform"]
+        Identity["Identity Module\n(Auth + Users)"]
+        CMS["CMS Module\n(Content Mgmt)"]
+        Availability["Availability Module\n(System Status)"]
+        Core["Core / Shell\n(Domain entities, DbContext, Module I/F)"]
+    end
+
+    Identity --> Core
+    CMS --> Core
+    Availability --> Core
+
+    Platform --> AdminFrontend["Admin Frontend\n(React SPA)"]
+    Platform --> ExternalClients["External Clients\n(API consumers)"]
+
+    style Identity fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style CMS fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style Availability fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style Core fill:#FFC107,stroke:#F57F17,color:#000
+    style AdminFrontend fill:#2196F3,stroke:#0D47A1,color:#fff
+    style ExternalClients fill:#9E9E9E,stroke:#424242,color:#fff
 ```

 ## Business Description
@@ -7,60 +7,71 @@

 ## Project Structure

-```
-SlpModularCms/
-+-- src/
-|   +-- SlpModularCms.Api/                     # API host
-|   |   +-- Extensions/
-|   |   |   +-- ServiceCollectionExtensions.cs # DI setup (JWT, Identity, EF, Auth)
-|   |   +-- Infrastructure/                    # Global exception handler
-|   |   +-- Properties/launchSettings.json
-|   |   +-- Program.cs                         # App startup and module loading
-|   |   +-- appsettings.json
-|   |   +-- appsettings.local.json             # Local dev overrides
-|   |
-|   +-- SlpModularCms.Core/                    # Shared core
-|   |   +-- Availability/
-|   |   |   +-- AvailabilityOptions.cs         # Circuit breaker config
-|   |   |   +-- AvailabilityStatus.cs          # Enum: Available, Maintenance, Unavailable
-|   |   +-- Data/
-|   |   |   +-- ApplicationDbContext.cs        # EF Core DbContext
-|   |   +-- Exceptions/                        # Custom exception types
-|   |   +-- Identity/
-|   |   |   +-- Authorization/                 # Policy handlers
-|   |   |   +-- Entities/
-|   |   |   |   +-- ApplicationUser.cs         # IdentityUser<Guid> + IsActive + CreatedAt
-|   |   |   |   +-- ApplicationRole.cs         # IdentityRole<Guid>
-|   |   |   |   +-- RefreshToken.cs            # Refresh token entity
-|   |   |   |   +-- Invitation.cs              # Invite entity with expiry
-|   |   |   |   +-- GlobalAvailabilityState.cs # Persisted system status
-|   |   |   +-- Models/                        # DTOs/request-response models
-|   |   |   +-- Services/
-|   |   |       +-- AuthService.cs             # JWT generation + token validation
-|   |   |       +-- InvitationService.cs       # Invite creation + completion
-|   |   |       +-- SetupService.cs            # Initial owner creation
-|   |   +-- Migrations/                        # EF Core migrations
-|   |   +-- Modules/
-|   |       +-- IModule.cs                     # Module interface (Name, Version, RegisterServices, UseModule)
-|   |       +-- ModuleInfo.cs                  # Module metadata record
-|   |
-|   +-- SlpModularCms.Modules.Identity/        # Identity feature module
-|   |   +-- Controllers/
-|   |       +-- AuthController.cs              # /auth/* endpoints
-|   |       +-- SetupController.cs             # /setup/* endpoints
-|   |       +-- UsersController.cs             # /users/* endpoints
-|   |
-|   +-- SlpModularCms.Modules.Availability/    # Availability feature module
-|   |   +-- Controllers/
-|   |   |   +-- AvailabilityController.cs      # /availability/* endpoints
-|   |   +-- Middleware/                        # Availability check middleware
-|   |   +-- Services/
-|   |       +-- PersistentAvailabilityService.cs  # Reads/writes status to DB + cache
-|   |
-|   +-- SlpModularCms.Core.Tests/              # Core unit tests
-|   +-- SlpModularCms.Modules.Availability.Tests/  # Availability unit tests
-|
-+-- aidlc-docs/                               # AI-DLC workflow documentation
+```mermaid
+graph TD
+    Root["SlpModularCms/"]
+    Src["src/"]
+    Api["SlpModularCms.Api\n(API host)"]
+    ApiExt["Extensions/\nServiceCollectionExtensions.cs"]
+    ApiInfra["Infrastructure/\nGlobal exception handler"]
+    ApiProg["Program.cs\nApp startup + module loading"]
+
+    Core["SlpModularCms.Core\n(Shared core)"]
+    CoreAvail["Availability/\nAvailabilityOptions.cs\nAvailabilityStatus.cs"]
+    CoreData["Data/\nApplicationDbContext.cs"]
+    CoreIdentity["Identity/\nEntities, Models, Services\nAuthorization/"]
+    CoreMigrations["Migrations/\nEF Core migrations"]
+    CoreModules["Modules/\nIModule.cs, ModuleInfo.cs"]
+
+    ModIdentity["SlpModularCms.Modules.Identity\n(Identity module)"]
+    ModIdentityCtrl["Controllers/\nAuthController\nSetupController\nUsersController"]
+
+    ModAvail["SlpModularCms.Modules.Availability\n(Availability module)"]
+    ModAvailCtrl["Controllers/\nAvailabilityController"]
+    ModAvailSvc["Services/\nPersistentAvailabilityService"]
+
+    Tests1["SlpModularCms.Core.Tests"]
+    Tests2["SlpModularCms.Modules.Availability.Tests"]
+    Docs["aidlc-docs/\nAI-DLC workflow documentation"]
+
+    Root --> Src
+    Root --> Docs
+    Src --> Api
+    Src --> Core
+    Src --> ModIdentity
+    Src --> ModAvail
+    Src --> Tests1
+    Src --> Tests2
+    Api --> ApiExt
+    Api --> ApiInfra
+    Api --> ApiProg
+    Core --> CoreAvail
+    Core --> CoreData
+    Core --> CoreIdentity
+    Core --> CoreMigrations
+    Core --> CoreModules
+    ModIdentity --> ModIdentityCtrl
+    ModAvail --> ModAvailCtrl
+    ModAvail --> ModAvailSvc
+
+    style Api fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style ApiExt fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style ApiInfra fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style ApiProg fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style Core fill:#FFC107,stroke:#F57F17,color:#000
+    style CoreAvail fill:#FFC107,stroke:#F57F17,color:#000
+    style CoreData fill:#FFC107,stroke:#F57F17,color:#000
+    style CoreIdentity fill:#FFC107,stroke:#F57F17,color:#000
+    style CoreMigrations fill:#FFC107,stroke:#F57F17,color:#000
+    style CoreModules fill:#FFC107,stroke:#F57F17,color:#000
+    style ModIdentity fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style ModIdentityCtrl fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style ModAvail fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style ModAvailCtrl fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style ModAvailSvc fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style Tests1 fill:#9E9E9E,stroke:#424242,color:#fff
+    style Tests2 fill:#9E9E9E,stroke:#424242,color:#fff
+    style Docs fill:#CE93D8,stroke:#6A1B9A,color:#000
 ```

 ## Key Classes/Modules
@@ -2,27 +2,33 @@

 ## Internal Dependencies

-```
-SlpModularCms.Api
-  +-- SlpModularCms.Core (compile)
-  +-- SlpModularCms.Modules.Identity (compile)
-  +-- SlpModularCms.Modules.Availability (compile)
+```mermaid
+graph TD
+    Api["SlpModularCms.Api"]
+    Core["SlpModularCms.Core"]
+    ModIdentity["SlpModularCms.Modules.Identity"]
+    ModAvail["SlpModularCms.Modules.Availability"]
+    CoreTests["SlpModularCms.Core.Tests"]
+    AvailTests["SlpModularCms.Modules.Availability.Tests"]
+    Frontend["SlpModularCms.Frontend\n(to be built)"]

-SlpModularCms.Modules.Identity
-  +-- SlpModularCms.Core (compile)
+    Api -->|compile| Core
+    Api -->|compile| ModIdentity
+    Api -->|compile| ModAvail
+    ModIdentity -->|compile| Core
+    ModAvail -->|compile| Core
+    CoreTests -->|test| Core
+    AvailTests -->|test| ModAvail
+    AvailTests -->|test| Core
+    Frontend -->|runtime REST| Api

-SlpModularCms.Modules.Availability
-  +-- SlpModularCms.Core (compile)
-
-SlpModularCms.Core.Tests
-  +-- SlpModularCms.Core (test)
-
-SlpModularCms.Modules.Availability.Tests
-  +-- SlpModularCms.Modules.Availability (test)
-  +-- SlpModularCms.Core (test)
-
-SlpModularCms.Frontend (to be built)
-  +-- SlpModularCms.Api (runtime via REST HTTP)
+    style Api fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style Core fill:#FFC107,stroke:#F57F17,color:#000
+    style ModIdentity fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style ModAvail fill:#4CAF50,stroke:#2E7D32,color:#fff
+    style CoreTests fill:#9E9E9E,stroke:#424242,color:#fff
+    style AvailTests fill:#9E9E9E,stroke:#424242,color:#fff
+    style Frontend fill:#2196F3,stroke:#0D47A1,color:#fff
 ```

 ### Dependency Details
@@ -31,7 +31,7 @@

 ### Frameworks
 - React 18.3.1 — UI framework
- React Router v7 (7.13.0) — Client-side routing
+- TanStack Router — Client-side routing (replaces React Router v7 from example app; chosen for full TypeScript safety and modern routing features)
 - Tailwind CSS v4 (4.1.12) — Utility-first CSS framework
 - shadcn/ui (via Radix UI) — Accessible component primitives