# asydikov/cards architecture

> Architecture diagram of the GitHub repository asydikov/cards, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asydikov/cards
- Repository: https://github.com/asydikov/cards

## Overview

1. **Top-level shape**
   This repository is a three-tier full-stack application:
   - **Cards.SPA**: Angular 8 single-page client
   - **Cards.API**: ASP.NET Core Web API edge layer
   - **Cards.Core**: shared business/domain/data-access layer
   The intended deployment boundary is browser → API → SQL Server, with JWT-based authentication crossing between client and API.

2. **Client subsystem: Cards.SPA**
   The Angular app owns all user interaction, routing, and form flow. Its main screens are:
   - login / register
   - card practice
   - note management
   - dictionary editors for categories, modes, and repeat rates
   The SPA is organized by feature folders, with shared services and models under `_services`, `_helpers`, and `_models`.

3. **Client-to-API integration**
   Angular talks to the backend through typed service classes such as `card.service.ts`, `user.service.ts`, etc. Cross-cutting HTTP concerns are handled by interceptors:
   - JWT attachment to outgoing requests
   - centralized error handling
   The `auth-guard.ts` protects authenticated routes, so auth state is enforced both at navigation level and at request level.

4. **API edge layer: Cards.API**
   `Cards.API` is the HTTP boundary. It contains controllers for the major resources:
   - `CardsController`
   - `NotesController`
   - `CategoriesController`
   - `ModesController`
   - `RepeatRatesController`
   - `UsersController`
   Controllers inherit from a base API controller, and responses/errors are standardized through middleware and shared response models.

5. **Backend composition and request handling**
   The API project is thin by design. Its main job is:
   - map HTTP routes to application operations
   - authenticate/authorize requests
   - translate domain exceptions into HTTP responses
   - bootstrap DI, middleware, and configuration
   `ErrorHandlerMiddleware` is a key boundary component for consistent exception handling.

6. **Core business layer: Cards.Core**
   `Cards.Core` is the main application layer. It contains:
   - domain entities
   - DTO/view models
   - services
   - repositories
   - authentication primitives
   - EF Core context/migrations
   This is where the actual application rules live; the API layer delegates to it rather than implementing business logic directly.

7. **Persistence model and data access**
   Entity Framework Core is used for SQL Server persistence. The `EF` folder contains:
   - `CardContext`
   - model configuration helpers
   - SQL settings
   The `Migrations` folder shows that the database schema is code-first and versioned in the repo. Repository classes wrap the context and provide per-entity persistence access.

8. **Domain objects and supporting dictionaries**
   The core domain centers on:
   - `Card`
   - `Note`
   - `User`
   - and supporting classification entities `Category`, `Mode`, `RepeatRate`
   These “dictionary” entities are used to organize cards by language/type/repetition behavior, matching the educational flashcard use case described in the README.

9. **Service/repository layering**
   The architecture follows a service-over-repository pattern:
   - repositories handle CRUD and database queries
   - services implement application behavior and validation
   - interfaces are used throughout for testability and loose coupling
   There are dedicated services and repositories for each major entity, which suggests the application is designed for easy extension by adding another entity-specific pair.

10. **Authentication and security**
   JWT authentication is implemented in `Cards.Core/Auth` with a handler, token model, and options object. The login/register flow in the SPA likely calls the API to receive a token, which is then stored client-side and attached to later requests. User management is a first-class part of the model rather than an external identity provider integration.

11. **Shared models and response contracts**
   The core layer defines model classes and standardized response wrappers such as `OkResponse` and `DictionaryOkResponse`. These are consumed by the SPA’s mirrored TypeScript models. This creates a stable contract between frontend and backend and reduces coupling to EF entities.

12. **Configuration and environment**
   Connection strings and token settings are configured through `appsettings.json` files in the API and Core projects. The README indicates SQL Server is the backing store, with Docker as an option for infrastructure setup. Angular environment files handle client-side build-time configuration.

13. **How a typical request flows**
   A browser action in Angular calls a service, the JWT interceptor adds credentials, the API controller receives the request, delegates to a Core service, which uses a repository and EF Core context to read/write SQL Server, then returns a standardized response model back through the API to the SPA.

14. **What to draw in an architecture diagram**
   The key diagram boundaries are:
   - Browser/UI boundary: Angular SPA
   - API boundary: ASP.NET Core controllers + middleware
   - Application boundary: Core services and repositories
   - Infrastructure boundary: EF Core + SQL Server
   Show JWT as the main cross-cutting security mechanism and note that cards, notes, users, and dictionary lookups are separate but related business areas.

Main entry points: [`Cards.Core/Services`](https://github.com/asydikov/cards/blob/master/Cards.Core/Services) (App Services), [`Cards.API/Controllers/BaseApiController.cs`](https://github.com/asydikov/cards/blob/master/Cards.API/Controllers/BaseApiController.cs) (Base Controller), [`Cards.API/Controllers/UsersController.cs`](https://github.com/asydikov/cards/blob/master/Cards.API/Controllers/UsersController.cs) (Users API), [`Cards.API/Startup.cs`](https://github.com/asydikov/cards/blob/master/Cards.API/Startup.cs) (API Host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Cards.SPA"]
  node_browser(("Browser UI<br/>client<br/>[app]"))
  node_spa_components["Screens<br/>angular views<br/>[app]"]
  node_spa_services["API Services<br/>typed clients<br/>[_services]"]
  node_spa_helpers{{"Auth Guards<br/>interceptors<br/>[_helpers]"}}
end

subgraph group_api["Cards.API"]
  node_api_entry(("API Host<br/>startup<br/>[Startup.cs]"))
  node_api_middleware["Error Middleware"]
  node_api_base["Base Controller<br/>controller base"]
  node_api_cards["Cards API<br/>controller<br/>[CardsController.cs]"]
  node_api_notes["Notes API<br/>controller<br/>[NotesController.cs]"]
  node_api_dicts["Dictionary APIs<br/>controllers"]
  node_api_users["Users API<br/>controller<br/>[UsersController.cs]"]
end

subgraph group_core["Cards.Core"]
  node_core_auth{{"JWT Auth<br/>[Auth]"}}
  node_core_services["App Services<br/>service layer<br/>[Services]"]
  node_core_repos["Repositories<br/>data access<br/>[Repositories]"]
  node_core_models["Contracts<br/>dto/models<br/>[Models]"]
  node_core_entities[("Domain Entities<br/>[Entities]")]
end

subgraph group_data["Persistence"]
  node_core_ef["EF Core<br/>orm<br/>[EF]"]
  node_sql_server[("SQL Server<br/>database")]
end

node_browser -->|"uses"| node_spa_components
node_spa_components -->|"calls"| node_spa_services
node_spa_services -->|"passes through"| node_spa_helpers
node_spa_helpers -->|"HTTP"| node_api_entry
node_api_entry -->|"configures"| node_api_middleware
node_api_entry -->|"hosts"| node_api_base
node_api_base -->|"routes"| node_api_cards
node_api_base -->|"routes"| node_api_notes
node_api_base -->|"routes"| node_api_dicts
node_api_base -->|"routes"| node_api_users
node_api_cards -->|"delegates"| node_core_services
node_api_notes -->|"delegates"| node_core_services
node_api_dicts -->|"delegates"| node_core_services
node_api_users -->|"auth"| node_core_auth
node_api_users -->|"delegates"| node_core_services
node_core_services -->|"uses"| node_core_repos
node_core_repos -->|"uses"| node_core_ef
node_core_ef -->|"persists to"| node_sql_server
node_core_services -->|"returns"| node_core_models
node_core_services -->|"operates on"| node_core_entities
node_api_users -.->|"returns token"| node_browser

click node_browser "https://github.com/asydikov/cards/blob/master/Cards.SPA/src/app"
click node_spa_components "https://github.com/asydikov/cards/blob/master/Cards.SPA/src/app"
click node_spa_services "https://github.com/asydikov/cards/blob/master/Cards.SPA/src/app/_services"
click node_spa_helpers "https://github.com/asydikov/cards/blob/master/Cards.SPA/src/app/_helpers"
click node_api_entry "https://github.com/asydikov/cards/blob/master/Cards.API/Startup.cs"
click node_api_middleware "https://github.com/asydikov/cards/blob/master/Cards.API/Middleware/ErrorHandlerMiddleware.cs"
click node_api_base "https://github.com/asydikov/cards/blob/master/Cards.API/Controllers/BaseApiController.cs"
click node_api_cards "https://github.com/asydikov/cards/blob/master/Cards.API/Controllers/CardsController.cs"
click node_api_notes "https://github.com/asydikov/cards/blob/master/Cards.API/Controllers/NotesController.cs"
click node_api_dicts "https://github.com/asydikov/cards/blob/master/Cards.API/Controllers/CategoriesController.cs"
click node_api_users "https://github.com/asydikov/cards/blob/master/Cards.API/Controllers/UsersController.cs"
click node_core_auth "https://github.com/asydikov/cards/blob/master/Cards.Core/Auth"
click node_core_services "https://github.com/asydikov/cards/blob/master/Cards.Core/Services"
click node_core_repos "https://github.com/asydikov/cards/blob/master/Cards.Core/Repositories"
click node_core_models "https://github.com/asydikov/cards/blob/master/Cards.Core/Models"
click node_core_entities "https://github.com/asydikov/cards/blob/master/Cards.Core/Entities"
click node_core_ef "https://github.com/asydikov/cards/blob/master/Cards.Core/EF"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_spa_components,node_spa_services,node_spa_helpers toneBlue
class node_api_entry,node_api_middleware,node_api_base,node_api_cards,node_api_notes,node_api_dicts,node_api_users toneAmber
class node_core_auth,node_core_services,node_core_repos,node_core_models,node_core_entities toneMint
class node_core_ef,node_sql_server toneRose
```

## Components

### Cards.SPA

Angular client with routing, auth flow, feature screens, and typed API services.

- [Browser UI](https://github.com/asydikov/cards/blob/master/Cards.SPA/src/app): client · User-facing SPA entry point and interaction boundary. · `Cards.SPA/src/app`
- [Screens](https://github.com/asydikov/cards/blob/master/Cards.SPA/src/app): angular views · Login, register, card practice, note management, and dictionary editors. · `Cards.SPA/src/app`
- [API Services](https://github.com/asydikov/cards/blob/master/Cards.SPA/src/app/_services): typed clients · Feature services that call backend endpoints for cards, notes, users, and dictionaries. · `Cards.SPA/src/app/_services`
- [Auth Guards](https://github.com/asydikov/cards/blob/master/Cards.SPA/src/app/_helpers): interceptors · JWT attachment, error handling, and route protection. · `Cards.SPA/src/app/_helpers`

### Cards.API

ASP.NET Core HTTP boundary with controllers, middleware, and bootstrapping.

- [API Host](https://github.com/asydikov/cards/blob/master/Cards.API/Startup.cs): startup · Program/Startup bootstrap for middleware, DI, and configuration. · `Cards.API/Startup.cs`
- [Error Middleware](https://github.com/asydikov/cards/blob/master/Cards.API/Middleware/ErrorHandlerMiddleware.cs): middleware · Converts domain and runtime failures into consistent HTTP responses. · `Cards.API/Middleware/ErrorHandlerMiddleware.cs`
- [Base Controller](https://github.com/asydikov/cards/blob/master/Cards.API/Controllers/BaseApiController.cs): controller base · Shared controller surface for API resource endpoints. · `Cards.API/Controllers/BaseApiController.cs`
- [Cards API](https://github.com/asydikov/cards/blob/master/Cards.API/Controllers/CardsController.cs): controller · HTTP endpoint for flashcard operations. · `Cards.API/Controllers/CardsController.cs`
- [Notes API](https://github.com/asydikov/cards/blob/master/Cards.API/Controllers/NotesController.cs): controller · HTTP endpoint for note operations. · `Cards.API/Controllers/NotesController.cs`
- [Dictionary APIs](https://github.com/asydikov/cards/blob/master/Cards.API/Controllers/CategoriesController.cs): controllers · Category, mode, and repeat-rate endpoints used by dictionary editors. · `Cards.API/Controllers/CategoriesController.cs`
- [Users API](https://github.com/asydikov/cards/blob/master/Cards.API/Controllers/UsersController.cs): controller · Login, register, and user management endpoints. · `Cards.API/Controllers/UsersController.cs`

### Cards.Core

Shared application layer with auth, domain models, services, repositories, and EF Core.

- [JWT Auth](https://github.com/asydikov/cards/blob/master/Cards.Core/Auth): auth · Token handling, JWT options, and auth handler used by the API and client flow. · `Cards.Core/Auth`
- [App Services](https://github.com/asydikov/cards/blob/master/Cards.Core/Services): service layer · Business logic, validation, encryption, and orchestration across entities. · `Cards.Core/Services`
- [Repositories](https://github.com/asydikov/cards/blob/master/Cards.Core/Repositories): data access · Entity-specific repository interfaces and implementations. · `Cards.Core/Repositories`
- [Contracts](https://github.com/asydikov/cards/blob/master/Cards.Core/Models): dto/models · Domain models, view models, and standardized response wrappers. · `Cards.Core/Models`
- [Domain Entities](https://github.com/asydikov/cards/blob/master/Cards.Core/Entities): entities · Card, note, user, and supporting dictionary entities. · `Cards.Core/Entities`

### Persistence

Entity Framework Core and SQL Server-backed storage.

- [EF Core](https://github.com/asydikov/cards/blob/master/Cards.Core/EF): orm · DbContext, model configuration, and migrations for the application schema. · `Cards.Core/EF`
- **SQL Server**: database · Persistent backing store for cards, notes, users, and dictionaries.

## Connections

- Browser UI → Screens: uses · The SPA renders the main user workflows.
- Screens → API Services: calls · Screens invoke typed services for server communication.
- API Services → Auth Guards: passes through · Requests are decorated by JWT and guarded by auth/error interceptors.
- Auth Guards → API Host: HTTP · Authenticated requests reach the API host.
- API Host → Error Middleware: configures · The host wires middleware into the request pipeline.
- API Host → Base Controller: hosts · Controllers inherit common API behavior.
- Base Controller → Cards API: routes · Base controller pattern is used by resource controllers.
- Base Controller → Notes API: routes · Base controller pattern is used by resource controllers.
- Base Controller → Dictionary APIs: routes · Base controller pattern is used by resource controllers.
- Base Controller → Users API: routes · Base controller pattern is used by resource controllers.
- Cards API → App Services: delegates · Card operations are implemented in the core service layer.
- Notes API → App Services: delegates · Note operations are implemented in the core service layer.
- Dictionary APIs → App Services: delegates · Dictionary endpoints use core services for CRUD and lookup behavior.
- Users API → JWT Auth: auth · Login and token issuance rely on JWT primitives.
- Users API → App Services: delegates · User flows are handled by core services.
- App Services → Repositories: uses · Services persist and query through repositories.
- Repositories → EF Core: uses · Repositories wrap the DbContext and EF mappings.
- EF Core → SQL Server: persists to · EF Core stores the code-first schema in SQL Server.
- App Services → Contracts: returns · Services exchange DTOs and standardized response models.
- App Services → Domain Entities: operates on · Business rules are centered on the domain entities.
- Users API → Browser UI: returns token · Authentication responses flow back to the SPA for later requests.