# archilk-cool/todosolution architecture

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

- Interactive diagram: https://gitdiagram.com/archilk-cool/todosolution
- Repository: https://github.com/archilk-cool/todosolution

## Overview

1. This repository is a two-app full-stack solution: a .NET 9 Web API backend in `src/Backend.TodoApi` and a React/Vite single-page frontend in `src/Frontend.todo-app`, with backend tests under `tests/Backend.TodoApi.Tests`.

2. The backend is organized as a layered API. HTTP requests enter versioned controllers under `Controllers/V1`, which delegate to a service interface/implementation pair in `Services`. The controller layer is intentionally thin and does not talk to EF Core directly.

3. The core domain is a single `TodoItem` model in `Models`. The API does not expose this entity directly; instead it uses versioned DTOs in `Dtos/V1` for create, update, and response shapes. That boundary is important for the architecture because it separates persistence concerns from the public contract.

4. Data access is handled through `AppDbContext` in `Data`, which is the EF Core unit of work for the application. The README indicates SQLite persistence via `todo.db`, so the backend’s data flow is controller → service → DbContext → SQLite, with EF Core translating the domain model to storage.

5. The backend also includes a mapping layer in `Mappings/TodoMappings.cs`. This is the explicit translation point between EF entities and API DTOs, keeping serialization and persistence models decoupled.

6. Cross-cutting concerns are centralized rather than spread through controllers. `Middleware/ErrorHandlingMiddleware.cs` provides global exception handling, and `Swagger/ConfigureSwaggerOptions.cs` supports OpenAPI docs. `Program.cs` is the composition root where DI, CORS, Swagger, and the request pipeline are wired together.

7. The frontend is a Vite-built React SPA. `main.jsx` boots the app, `App.jsx` holds the top-level UI composition, and the `components` folder contains the task input, list, item, editor, filter tabs, and empty-state pieces that make up the Todo workflow.

8. Frontend-to-backend communication is isolated in `src/api/todoApi.js`. That API client is the boundary between UI state and remote persistence; the UI components call into this client rather than speaking HTTP directly. The README notes `VITE_API_URL` as the environment-specific backend base URL, which makes the frontend deployment-agnostic.

9. UI styling is built from Tailwind plus a large set of shadcn/ui-style primitives under `src/components/ui`. Those components are not domain logic, but they are part of the presentation subsystem that supports the modern visual design, theme toggling, and reusable controls.

10. Testing is split along the same architectural boundaries. Backend tests use xUnit and EF Core InMemory to validate service and controller behavior without requiring SQLite. Frontend tests use Jest and React Testing Library to verify component behavior in isolation. This reinforces the repo’s separation between API logic, persistence, and presentation.

11. The main runtime flow is straightforward: a user interacts with the React SPA, the SPA sends REST/JSON requests to the versioned `/api/v1/todo` endpoints, the backend validates and maps DTOs, the service layer applies business rules, and EF Core persists changes to SQLite. Responses return as DTOs to the frontend, which re-renders the task list.

12. The solution is deliberately scoped as a single shared Todo list, but its architecture is already arranged for extension. Versioned controllers, DTOs, service interfaces, and a separate mapping layer would make it relatively easy to add auth, multiple lists, pagination, or a different database without collapsing the current boundaries.

Main entry points: [`src/Backend.TodoApi/Services/TodoService.cs`](https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Services/TodoService.cs) (Todo Service Impl), [`src/Backend.TodoApi/Program.cs`](https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Program.cs) (Program), [`src/Frontend.todo-app/src/App.jsx`](https://github.com/archilk-cool/todosolution/blob/master/src/Frontend.todo-app/src/App.jsx) (App), [`src/Frontend.todo-app/src/components/TodoList.jsx`](https://github.com/archilk-cool/todosolution/blob/master/src/Frontend.todo-app/src/components/TodoList.jsx) (Todo Components)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend API"]
  node_backend_program["Program<br/>composition root<br/>[Program.cs]"]
  node_backend_controller["Todo API<br/>v1 controller<br/>[TodoController.cs]"]
  node_backend_service_contract["Todo Service<br/>service interface<br/>[ITodoService.cs]"]
  node_backend_service_impl["Todo Service Impl<br/>domain service<br/>[TodoService.cs]"]
  node_backend_db[("App DbContext<br/>[AppDbContext.cs]")]
  node_backend_model["TodoItem<br/>domain model<br/>[TodoItem.cs]"]
  node_backend_dto_create["Create DTO<br/>api contract<br/>[TodoCreateDto.cs]"]
  node_backend_dto_update["Update DTO<br/>api contract<br/>[TodoUpdateDto.cs]"]
  node_backend_dto_response["Response DTO<br/>api contract<br/>[TodoResponseDto.cs]"]
  node_backend_mapping["Todo Mappings<br/>translation layer<br/>[TodoMappings.cs]"]
  node_backend_middleware["Error Middleware<br/>cross-cutting middleware"]
  node_backend_swagger["Swagger Config<br/>openapi setup"]
end

subgraph group_frontend["Frontend SPA"]
  node_frontend_main["main.jsx<br/>app bootstrap<br/>[main.jsx]"]
  node_frontend_app["App<br/>ui shell<br/>[App.jsx]"]
  node_frontend_api["Todo API Client<br/>http client<br/>[todoApi.js]"]
  node_frontend_components["Todo Components<br/>presentation components<br/>[TodoList.jsx]"]
  node_frontend_ui["UI Primitives<br/>shared component kit<br/>[button.tsx]"]
  node_frontend_styles["Styles<br/>tailwind styling<br/>[styles.css]"]
end

subgraph group_tests["Tests"]
  node_tests_backend_controller["Controller Tests<br/>xunit tests"]
  node_tests_backend_service["Service Tests<br/>xunit tests"]
  node_tests_frontend_components["Component Tests<br/>rtl tests<br/>[TaskInput.test.jsx]"]
end

node_backend_program -->|"maps routes"| node_backend_controller
node_backend_program -->|"registers"| node_backend_service_contract
node_backend_program -->|"configures"| node_backend_db
node_backend_program -->|"adds"| node_backend_middleware
node_backend_program -->|"enables"| node_backend_swagger
node_backend_controller -->|"depends on"| node_backend_service_contract
node_backend_service_impl -->|"implements"| node_backend_service_contract
node_backend_service_impl -->|"uses"| node_backend_db
node_backend_service_impl -->|"maps"| node_backend_mapping
node_backend_service_impl -->|"persists"| node_backend_model
node_backend_service_impl -->|"accepts"| node_backend_dto_create
node_backend_service_impl -->|"accepts"| node_backend_dto_update
node_backend_service_impl -->|"returns"| node_backend_dto_response
node_backend_db -->|"tracks"| node_backend_model
node_frontend_main -->|"boots"| node_frontend_app
node_frontend_app -->|"composes"| node_frontend_components
node_frontend_app -->|"calls"| node_frontend_api
node_frontend_components -->|"fetches"| node_frontend_api
node_frontend_components -->|"renders with"| node_frontend_ui
node_frontend_app -->|"styles with"| node_frontend_styles
node_tests_backend_controller -.->|"verifies"| node_backend_controller
node_tests_backend_service -.->|"verifies"| node_backend_service_impl
node_tests_frontend_components -.->|"verifies"| node_frontend_components

click node_backend_program "https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Program.cs"
click node_backend_controller "https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Controllers/V1/TodoController.cs"
click node_backend_service_contract "https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Services/ITodoService.cs"
click node_backend_service_impl "https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Services/TodoService.cs"
click node_backend_db "https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Data/AppDbContext.cs"
click node_backend_model "https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Models/TodoItem.cs"
click node_backend_dto_create "https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Dtos/V1/TodoCreateDto.cs"
click node_backend_dto_update "https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Dtos/V1/TodoUpdateDto.cs"
click node_backend_dto_response "https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Dtos/V1/TodoResponseDto.cs"
click node_backend_mapping "https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Mappings/TodoMappings.cs"
click node_backend_middleware "https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Middleware/ErrorHandlingMiddleware.cs"
click node_backend_swagger "https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Swagger/ConfigureSwaggerOptions.cs"
click node_frontend_main "https://github.com/archilk-cool/todosolution/blob/master/src/Frontend.todo-app/src/main.jsx"
click node_frontend_app "https://github.com/archilk-cool/todosolution/blob/master/src/Frontend.todo-app/src/App.jsx"
click node_frontend_api "https://github.com/archilk-cool/todosolution/blob/master/src/Frontend.todo-app/src/api/todoApi.js"
click node_frontend_components "https://github.com/archilk-cool/todosolution/blob/master/src/Frontend.todo-app/src/components/TodoList.jsx"
click node_frontend_ui "https://github.com/archilk-cool/todosolution/blob/master/src/Frontend.todo-app/src/components/ui/button.tsx"
click node_frontend_styles "https://github.com/archilk-cool/todosolution/blob/master/src/Frontend.todo-app/src/styles.css"
click node_tests_backend_controller "https://github.com/archilk-cool/todosolution/blob/master/tests/Backend.TodoApi.Tests/TodoControllerTests.cs"
click node_tests_backend_service "https://github.com/archilk-cool/todosolution/blob/master/tests/Backend.TodoApi.Tests/TodoServiceTests.cs"
click node_tests_frontend_components "https://github.com/archilk-cool/todosolution/blob/master/src/Frontend.todo-app/src/components/__tests__/TaskInput.test.jsx"

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_backend_program,node_backend_controller,node_backend_service_contract,node_backend_service_impl,node_backend_db,node_backend_model,node_backend_dto_create,node_backend_dto_update,node_backend_dto_response,node_backend_mapping,node_backend_middleware,node_backend_swagger toneBlue
class node_frontend_main,node_frontend_app,node_frontend_api,node_frontend_components,node_frontend_ui,node_frontend_styles toneAmber
class node_tests_backend_controller,node_tests_backend_service,node_tests_frontend_components toneMint
```

## Components

### Backend API

ASP.NET Core API, domain, persistence, and cross-cutting pipeline

- [Program](https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Program.cs): composition root · Wires DI, middleware, CORS, Swagger, and the request pipeline · `src/Backend.TodoApi/Program.cs`
- [Todo API](https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Controllers/V1/TodoController.cs): v1 controller · Thin versioned HTTP entrypoint for Todo operations · `src/Backend.TodoApi/Controllers/V1/TodoController.cs`
- [Todo Service](https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Services/ITodoService.cs): service interface · Public backend abstraction used by controllers · `src/Backend.TodoApi/Services/ITodoService.cs`
- [Todo Service Impl](https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Services/TodoService.cs): domain service · Implements business rules and coordinates data access · `src/Backend.TodoApi/Services/TodoService.cs`
- [App DbContext](https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Data/AppDbContext.cs): ef core unit of work · EF Core persistence boundary for Todo data · `src/Backend.TodoApi/Data/AppDbContext.cs`
- [TodoItem](https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Models/TodoItem.cs): domain model · Core persisted Todo entity · `src/Backend.TodoApi/Models/TodoItem.cs`
- [Create DTO](https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Dtos/V1/TodoCreateDto.cs): api contract · Versioned input shape for creating todos · `src/Backend.TodoApi/Dtos/V1/TodoCreateDto.cs`
- [Update DTO](https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Dtos/V1/TodoUpdateDto.cs): api contract · Versioned input shape for updating todos · `src/Backend.TodoApi/Dtos/V1/TodoUpdateDto.cs`
- [Response DTO](https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Dtos/V1/TodoResponseDto.cs): api contract · Versioned output shape returned to clients · `src/Backend.TodoApi/Dtos/V1/TodoResponseDto.cs`
- [Todo Mappings](https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Mappings/TodoMappings.cs): translation layer · Explicit mapping boundary between entities and DTOs · `src/Backend.TodoApi/Mappings/TodoMappings.cs`
- [Error Middleware](https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Middleware/ErrorHandlingMiddleware.cs): cross-cutting middleware · Global exception handling for the API pipeline · `src/Backend.TodoApi/Middleware/ErrorHandlingMiddleware.cs`
- [Swagger Config](https://github.com/archilk-cool/todosolution/blob/master/src/Backend.TodoApi/Swagger/ConfigureSwaggerOptions.cs): openapi setup · Configures versioned OpenAPI documentation · `src/Backend.TodoApi/Swagger/ConfigureSwaggerOptions.cs`

### Frontend SPA

React/Vite application and presentation layer

- [main.jsx](https://github.com/archilk-cool/todosolution/blob/master/src/Frontend.todo-app/src/main.jsx): app bootstrap · Bootstraps the React application · `src/Frontend.todo-app/src/main.jsx`
- [App](https://github.com/archilk-cool/todosolution/blob/master/src/Frontend.todo-app/src/App.jsx): ui shell · Top-level composition for the Todo UI · `src/Frontend.todo-app/src/App.jsx`
- [Todo API Client](https://github.com/archilk-cool/todosolution/blob/master/src/Frontend.todo-app/src/api/todoApi.js): http client · Isolates frontend calls to the backend REST API · `src/Frontend.todo-app/src/api/todoApi.js`
- [Todo Components](https://github.com/archilk-cool/todosolution/blob/master/src/Frontend.todo-app/src/components/TodoList.jsx): presentation components · Task input, list, editor, filters, and empty-state UI · `src/Frontend.todo-app/src/components/TodoList.jsx`
- [UI Primitives](https://github.com/archilk-cool/todosolution/blob/master/src/Frontend.todo-app/src/components/ui/button.tsx): shared component kit · Reusable shadcn-style controls and presentation primitives · `src/Frontend.todo-app/src/components/ui/button.tsx`
- [Styles](https://github.com/archilk-cool/todosolution/blob/master/src/Frontend.todo-app/src/styles.css): tailwind styling · Global styling and theme support for the SPA · `src/Frontend.todo-app/src/styles.css`

### Tests

Backend and frontend verification boundaries

- [Controller Tests](https://github.com/archilk-cool/todosolution/blob/master/tests/Backend.TodoApi.Tests/TodoControllerTests.cs): xunit tests · Validates API behavior without a real SQLite dependency · `tests/Backend.TodoApi.Tests/TodoControllerTests.cs`
- [Service Tests](https://github.com/archilk-cool/todosolution/blob/master/tests/Backend.TodoApi.Tests/TodoServiceTests.cs): xunit tests · Validates service logic with in-memory EF Core · `tests/Backend.TodoApi.Tests/TodoServiceTests.cs`
- [Component Tests](https://github.com/archilk-cool/todosolution/blob/master/src/Frontend.todo-app/src/components/__tests__/TaskInput.test.jsx): rtl tests · Verifies component behavior in isolation · `src/Frontend.todo-app/src/components/__tests__/TaskInput.test.jsx`

## Connections

- Program → Todo API: maps routes · Registers and exposes the versioned controller pipeline
- Program → Todo Service: registers · Adds service abstraction to dependency injection
- Program → App DbContext: configures · Sets up EF Core persistence and database access
- Program → Error Middleware: adds · Installs global exception handling in the request pipeline
- Program → Swagger Config: enables · Configures API documentation and versioned OpenAPI output
- Todo API → Todo Service: depends on · Controller delegates work to the service interface
- Todo Service Impl → Todo Service: implements · Concrete business service behind the controller contract
- Todo Service Impl → App DbContext: uses · Reads and writes Todo entities through EF Core
- Todo Service Impl → Todo Mappings: maps · Translates between persistence models and API DTOs
- Todo Service Impl → TodoItem: persists · Operates on the Todo entity model
- Todo Service Impl → Create DTO: accepts · Consumes create requests via DTOs
- Todo Service Impl → Update DTO: accepts · Consumes update requests via DTOs
- Todo Service Impl → Response DTO: returns · Produces response DTOs for API consumers
- App DbContext → TodoItem: tracks · EF Core maps the TodoItem entity to storage
- main.jsx → App: boots · Mounts the top-level React application
- App → Todo Components: composes · Builds the Todo workflow from feature components
- App → Todo API Client: calls · Uses the API client for remote persistence
- Todo Components → Todo API Client: fetches · Delegates CRUD requests to the client boundary
- Todo Components → UI Primitives: renders with · Uses shared UI primitives for controls and layout
- App → Styles: styles with · Applies global and theme styling
- Controller Tests → Todo API: verifies · Exercises HTTP layer behavior
- Service Tests → Todo Service Impl: verifies · Exercises service logic against in-memory persistence
- Component Tests → Todo Components: verifies · Exercises component behavior in isolation