102 lines
8.1 KiB
Markdown
102 lines
8.1 KiB
Markdown
---
|
|
type: Reference
|
|
title: Source Code Map & Navigation Directory
|
|
description: Practical navigation guide mapping source files across projects to system domains, viewmodels, services, and responsibilities.
|
|
tags: [source-map, navigation, directory, projects, maui, mvvm]
|
|
openwiki:
|
|
roles: [repository]
|
|
change_kinds: [public-api]
|
|
source_paths: [SlipItIn/MauiProgram.cs, SlipItIn.Server/Program.cs, SlipItIn.AppHost/AppHost.cs]
|
|
symbols: [MauiProgram, Program, AppHost]
|
|
validation_commands: ["dotnet build SlipItIn.slnx"]
|
|
---
|
|
|
|
# Source Code Map & Navigation Directory
|
|
|
|
This directory maps every major project, folder, and source file in the SlipItIn repository to its system domain and technical responsibility.
|
|
|
|
This navigation map [indexes backend architecture files described in](/openwiki/architecture/overview.md) the system architecture, [indexes domain model files defined in](/openwiki/domain/game-mechanics.md) the domain mechanics guide, [indexes workflow implementation files detailed in](/openwiki/workflows/slip-and-challenge.md) the workflow guide, and [indexes operational configuration files documented in](/openwiki/operations/runbook.md) the operations runbook.
|
|
|
|
---
|
|
|
|
## 1. Solution Projects (`SlipItIn.slnx`)
|
|
|
|
```
|
|
SlipItIn.slnx
|
|
├── SlipItIn.AppHost/ # Aspire distributed orchestrator
|
|
├── SlipItIn.Server/ # Web API & SignalR real-time server
|
|
├── SlipItIn.Shared/ # Shared models, DTOs & enums
|
|
├── SlipItIn.ServiceDefaults/ # Aspire OpenTelemetry & health checks
|
|
├── SlipItIn/ # .NET MAUI multi-platform client (MVVM)
|
|
└── Agents/ # Architecture & planning briefs
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Directory & Source File Map
|
|
|
|
### `.NET Aspire Orchestration` (`SlipItIn.AppHost`)
|
|
- **`AppHost.cs`**: Orchestrates application dependencies. Configures PostgreSQL (`AddPostgres("pgsql")`), references `SlipItIn.Server`, and links the MAUI client.
|
|
- **`appsettings.json`**: Aspire orchestrator configuration.
|
|
|
|
### `Service Defaults & Telemetry` (`SlipItIn.ServiceDefaults`)
|
|
- **`Extensions.cs`**: Implements `AddServiceDefaults()` and `ConfigureOpenTelemetry()`. Configures OpenTelemetry logging, metrics, tracing filters (excluding `/health` and `/alive`), service discovery, and HTTP resilience handlers.
|
|
|
|
### `Backend Web API & SignalR Server` (`SlipItIn.Server`)
|
|
- **`Program.cs`**: Entrypoint for ASP.NET Core server. Registers EF Core `IDbContextFactory`, JWT authentication middleware, SignalR query parameter token parsing, Npgsql PostgreSQL data source, OpenAPI, CORS policies, and automatic EF migrations.
|
|
- **`Controllers/AuthController.cs`**: REST API controller providing `/api/auth/register`, `/api/auth/login`, and `/api/auth/me`. Handles BCrypt password hashing and JWT token generation.
|
|
- **`Hubs/GameHub.cs`**: SignalR hub mapped to `/hubs/game`. Performs JWT claim extraction (`GetAuthenticatedUserId`), player/host authorization checks (`ValidatePlayerAccessAsync`, `ValidateHostAccessAsync`), connection ID tracking, and real-time event broadcasting.
|
|
- **`Services/IGameService.cs`**: Contract interface defining backend game operations.
|
|
- **`Services/GameService.cs`**: Core engine implementation. Handles game creation, player joining, card dealing from active phrases, slip submission, challenge creation, penalty resolution, and state serialization (`GetGameStateAsync`, `GetPlayerHandAsync`). Adds `hostPlayer` directly to `game.Players` before `context.Games.Add(game)` for EF Core navigation safety.
|
|
- **`Data/SlipItInDbContext.cs`**: Entity Framework Core DbContext mapping `Users`, `Games`, `Players`, `Phrases`, `PlayerCards`, `GameRounds`, and `SlipChallenges` to PostgreSQL tables.
|
|
- **`Migrations/`**: Auto-generated EF Core migration snapshots (`20260723193505_InitialCreate.cs`).
|
|
- **`appsettings.json` & `appsettings.Development.json`**: JWT secret keys, issuer/audience defaults, and database connection strings.
|
|
|
|
### `Shared Domain & DTOs` (`SlipItIn.Shared`)
|
|
- **`Models/User.cs`**: Entity storing user credentials, BCrypt password hashes, and user state.
|
|
- **`Models/Game.cs`**: Entity storing lobby codes, status (`GameStatus`), host ID, and duration parameters.
|
|
- **`Models/Player.cs`**: Entity tracking player scores, ready status, and SignalR connection IDs.
|
|
- **`Models/Phrase.cs`**: Entity storing phrase text and creator metadata.
|
|
- **`Models/GameRound.cs`**: Entity tracking round numbers and status (`RoundStatus`).
|
|
- **`Models/PlayerCard.cs`**: Entity linking phrases to players for specific rounds (`IsUsed` flag).
|
|
- **`Models/SlipChallenge.cs`**: Entity recording accusations, challenging/target player IDs, and challenge status (`ChallengeStatus`).
|
|
- **`DTOs/AuthDtos.cs`**: DTOs for authentication (`RegisterRequestDto`, `LoginRequestDto`, `AuthResponseDto`).
|
|
- **`DTOs/GameStateDto.cs`**: DTOs for public state (`GameStateDto`, `PlayerInfoDto`), private hand state (`PlayerHandDto`, `PlayerCardDto`), and challenge alerts (`SlipChallengeDto`).
|
|
|
|
### `Cross-Platform MAUI Client` (`SlipItIn`)
|
|
- **`MauiProgram.cs`**: Client app builder. Configures dependency injection for ViewModels and Services, fonts, debug logging, and sets up `ServiceHelper.Services`.
|
|
- **`App.xaml` & `App.xaml.cs`**: Root MAUI application class.
|
|
- **`AppShell.xaml` & `AppShell.xaml.cs`**: Shell navigation container routing between `LoginPage`, `RegisterPage`, `LobbyPage`, and `GameBoardPage`.
|
|
- **`Infrastructure/ServiceHelper.cs`**: Static service locator bridge for runtime DI resolution.
|
|
- **`Services/`**:
|
|
- `SignalRService.cs` (`ISignalRService`): WebSocket SignalR client, hub method invoker, and auto-reconnect engine.
|
|
- `GameStateService.cs` (`IGameStateService`): Central game state holder, messenger bridge (`WeakReferenceMessenger`), and offline action queue manager.
|
|
- `LocalStorageService.cs` (`ILocalStorageService`): Dual-layer local persistence (`SecureStorage` for tokens, `Preferences` for game state/offline queue).
|
|
- `AuthSessionService.cs` (`IAuthSessionService`): Authenticated user session state manager.
|
|
- `ApiService.cs` (`IApiService`): REST HTTP client for authentication endpoints.
|
|
- `AppConfigurationService.cs` (`IAppConfigurationService`): Configuration provider for API base URL and SignalR Hub URL.
|
|
- **`ViewModels/`**:
|
|
- `BaseViewModel.cs`: Abstract base ViewModel providing `IsBusy`, `StatusMessage`, and error handling helper `RunSafeAsync`.
|
|
- `LoginViewModel.cs`: Handles email/password authentication and navigation to `LobbyPage`.
|
|
- `RegisterViewModel.cs`: Handles user registration.
|
|
- `LobbyViewModel.cs`: Manages lobby creation, joining, player readiness, and game start. Implements `IRecipient` interfaces for real-time messages.
|
|
- `GameBoardViewModel.cs`: Manages game board state, player cards, slip submission, challenging, challenge resolution, and offline queueing.
|
|
- **`Views/`**:
|
|
- `LoginPage.xaml` / `.cs`: XAML login UI view.
|
|
- `RegisterPage.xaml` / `.cs`: XAML registration UI view.
|
|
- `LobbyPage.xaml` / `.cs`: XAML lobby UI view displaying lobby code and player list.
|
|
- `GameBoardPage.xaml` / `.cs`: XAML game board UI view displaying cards and player list.
|
|
- `ChallengeNotificationOverlay.xaml` / `.cs`: Reusable overlay view for challenge alerts.
|
|
- **`Messages/`**:
|
|
- `LobbyCreatedMessage.cs`, `GameStateChangedMessage.cs`, `GameStartedMessage.cs`, `PlayerHandChangedMessage.cs`, `ChallengeReceivedMessage.cs`, `ErrorOccurredMessage.cs`, `ConnectionStateChangedMessage.cs`: Strongly-typed `CommunityToolkit.Mvvm.Messaging` payloads.
|
|
- **`Models/`**:
|
|
- `QueuedGameAction.cs`: Data model for offline game action queueing.
|
|
- **`Platforms/`**: Platform-specific entry points for Android, iOS, MacCatalyst, and Windows.
|
|
|
|
### `Documentation & Specifications` (`Agents/`)
|
|
- **`Agents/Architecture.md`**: Specification document defining backend security and client MVVM/stability patterns.
|
|
- **`Agents/ProjectPlan.md`**: Project plan breakdown covering development phases.
|
|
|
|
### `Automation & CI/CD` (`.github/workflows/`)
|
|
- **`.github/workflows/openwiki-update.yml`**: Scheduled GitHub Actions workflow executing `openwiki code --update` via Gemini Flash (`gemini-3.6-flash`) to keep repository documentation in sync with source changes.
|