How asydikov/cards works
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: Services App Services · BaseApiController.cs Base Controller · UsersController.cs Users API · Startup.cs API Host
Components 18
Cards.SPA
Angular client with routing, auth flow, feature screens, and typed API services.
- Browser UI · User-facing SPA entry point and interaction boundary.
Cards.SPA/src/app - Screens · Login, register, card practice, note management, and dictionary editors.
Cards.SPA/src/app - API Services · Feature services that call backend endpoints for cards, notes, users, and dictionaries.
Cards.SPA/src/app/_services - Auth Guards · 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 · Program/Startup bootstrap for middleware, DI, and configuration.
Cards.API/Startup.cs - Error Middleware · Converts domain and runtime failures into consistent HTTP responses.
Cards.API/Middleware/ErrorHandlerMiddleware.cs - Base Controller · Shared controller surface for API resource endpoints.
Cards.API/Controllers/BaseApiController.cs - Cards API · HTTP endpoint for flashcard operations.
Cards.API/Controllers/CardsController.cs - Notes API · HTTP endpoint for note operations.
Cards.API/Controllers/NotesController.cs - Dictionary APIs · Category, mode, and repeat-rate endpoints used by dictionary editors.
Cards.API/Controllers/CategoriesController.cs - Users API · 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 · Token handling, JWT options, and auth handler used by the API and client flow.
Cards.Core/Auth - App Services · Business logic, validation, encryption, and orchestration across entities.
Cards.Core/Services - Repositories · Entity-specific repository interfaces and implementations.
Cards.Core/Repositories - Contracts · Domain models, view models, and standardized response wrappers.
Cards.Core/Models - Domain Entities · Card, note, user, and supporting dictionary entities.
Cards.Core/Entities
Persistence
Entity Framework Core and SQL Server-backed storage.
- EF Core · DbContext, model configuration, and migrations for the application schema.
Cards.Core/EF - SQL Server · Persistent backing store for cards, notes, users, and dictionaries.
Connections 21
- 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.