Flashcard Viewer

A modern, multi-platform flashcard application built on .NET 10.0 utilizing a clean, decoupled architecture.

It is designed to run in multiple hosting environments:

1. Desktop/Mobile (Blazor Hybrid via .NET MAUI): Runs natively on Windows, macOS, Android, and iOS using a native WebView wrapper.
2. Web (Blazor WebAssembly): Runs entirely in-browser as a static single-page application.

The user interface is shared across all platforms in a unified Razor Class Library styled with custom Vanilla CSS (supporting dark/light theme toggles, glassmorphism panels, and 3D card flipping animations).

---

1. Solution Architecture

The repository is organized following clean architecture patterns:

Project Root
├── src/                         # Application Sources
│   ├── FlashcardViewer.Domain/        # Domain entities (Flashcard, FlashcardSet, SessionConfig)
│   ├── FlashcardViewer.Application/   # Repository interfaces and domain-use case contracts
│   ├── FlashcardViewer.SharedUI/      # Shared Razor pages, components, Router, and global CSS
│   ├── FlashcardViewer.Maui/          # Blazor Hybrid wrapper host (Windows, Android, MacCatalyst)
│   ├── FlashcardViewer.Wasm/          # Blazor WebAssembly static client host
│   ├── FlashcardViewer.Infrastructure.Sqlite/ # Direct SQLite database persistence layer for native host
│   └── FlashcardViewer.Infrastructure.Web/    # Browser LocalStorage persistence layer for WASM host
├── tests/                       # Testing & Verification Projects
│   ├── FlashcardViewer.UnitTests/     # TUnit functional verification (Domain models, lists, session progression)
│   ├── FlashcardViewer.ArchitectureTests/ # Programmatic dependency boundary validations (NetArchTest)
│   └── format-check.ps1               # Workspace format-conformity script
├── FlashcardViewer.slnx          # Solution XML configuration
└── global.json                  # SDK 10.0.300 pinning

Dependency Flow

• The core Domain and Application layers are pure and framework-agnostic.
• SharedUI and Infrastructure layers depend on the Application layer.
• Host projects (Maui, Wasm) reference the SharedUI layer and inject their respective storage adapters at startup via Dependency Injection.
• Architecture Tests programmatically ensure no reference violations can build.

---

2. Getting Started & Running the Application

Ensure you have the .NET 10 SDK (minimum 10.0.300) and the MAUI workloads installed on your development machine.

Run on Windows (Blazor Hybrid)

Executes natively as a WinUI 3 desktop application accessing local SQLite storage:

dotnet build src/FlashcardViewer.Maui/FlashcardViewer.csproj -f net10.0-windows10.0.26100.0
dotnet run --project src/FlashcardViewer.Maui/FlashcardViewer.csproj -f net10.0-windows10.0.26100.0 --no-launch-profile -p:WindowsPackageType=None

Run on Web (Blazor WebAssembly)

Runs in your default browser utilizing browser-based Web storage fallback:

dotnet run --project src/FlashcardViewer.Wasm/FlashcardViewer.Wasm.csproj

---

3. Testing and Verification

All test suites are implemented using the TUnit testing library.

Run Unit and Component Tests

dotnet run --project tests/FlashcardViewer.UnitTests

Run Architecture Integrity Tests

dotnet run --project tests/FlashcardViewer.ArchitectureTests

---

4. Repository Formatting Mandates

Before committing code or submitting pull requests, run the validation script to verify final newline and encoding requirements:

# Verify formatting status
powershell -File tests/format-check.ps1

# Automatically resolve formatting errors (newline adjustments and BOM removal)
powershell -File tests/format-check.ps1 -Fix