Imported from SamiUrRehman065/TrainWise (AGENTS.md). Install upstream with npx skills add SamiUrRehman065/TrainWise. Copyright stays with the author.

TrainWise Developer Guide & AI Agent Rules

This guide outlines the system architecture, build/test/run commands, code styles, and directory layout for TrainWise.

📁 Repository Directory Layout

• TrainWise.API/ — ASP.NET Core 8 Web API Gateway.
• TrainWise.Web/ — Blazor WebAssembly frontend dashboard.
• TrainWise.MLService/ — Python 3.11 machine learning microservice.
• docs/ — System architecture, SRS, and testing guides.
• scratch/ — End-to-end PowerShell verification scripts.

🛠️ CLI Run & Build Commands

Build Projects

• Solution Build: dotnet build

Running Services Locally

• API Gateway (C#): dotnet run --project TrainWise.API (Listens on port 5002 / 5003)
• Web Frontend (Blazor): dotnet run --project TrainWise.Web (Listens on port 53351 / 53352)
• ML Microservice (Python): Run from TrainWise.MLService/ using the virtual environment: ..\.venv311\Scripts\uvicorn app.main:app --host 127.0.0.1 --port 8000

🧪 Integration & E2E Tests

Run verification scripts from the root directory:

• Settings & Auth Verification: powershell -ExecutionPolicy Bypass -File scratch/verify_settings.ps1
• E2E Training Pipeline Verification: powershell -ExecutionPolicy Bypass -File scratch/verify_dataset_and_training.ps1
• Dataset Archiving & Restore Lifecycle: powershell -ExecutionPolicy Bypass -File scratch/verify_unarchive.ps1

🎨 Architectural Overview

1. Security & Redirection

• Instant Redirection: MainLayout.razor performs a synchronous sessionStorage token validation during OnInitialized via RestoreFromStorage.
• If unauthenticated, it redirects instantly to /login with zero UI flash or warning loading messages.
• Session Expiration: Token validity is set to exactly 15 minutes in appsettings.json. Old session entries are automatically evicted from DistributedSessionStore matching this TTL.

2. Dual Storage & Fallback Cache

• Storage Mode: Mapped in appsettings.json under DatasetStorage:Mode (SqlBlob or Disk).
• Self-Healing Fallback: DatasetStorageService reads, archives, and unarchives files transparently by looking up both SQL Blob storage and local disk caches. If the ML microservice lacks a file, the C# Gateway uploads it on-the-fly before request execution.

3. Background ML Training

• Model training is queued asynchronously using a thread-safe System.Threading.Channels queue in TrainingJobQueue to prevent gateway timeouts.
• Polled by the frontend via GET api/train/status/{jobId}.

📝 Code Style & Conventions

C# Guidelines

• PascalCase for Class, Method, and Property names.
• camelCase with a leading underscore (_fieldName) for private member fields.
• Prefix interfaces with I (e.g. IDatasetService).
• Standardize on Task, async, and await with CancellationToken support in controller and service layers.

Python Guidelines

• snake_case for variables, functions, and modules.
• PascalCase for classes.
• Standardize on FastAPI, Pydantic type annotation schemas, and scikit-learn standard metrics.

Blazor / Razor Guidelines

• Put all component code logic in @code { ... } blocks.
• Inject dependencies via @inject declarations.
• Follow HSL customized glassmorphic design variables from wwwroot/css/site.css and wwwroot/css/app.css for visual consistency.