# ovtsunova/appliance_store architecture

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

- Interactive diagram: https://gitdiagram.com/ovtsunova/appliance_store
- Repository: https://github.com/ovtsunova/appliance_store

## Overview

1. **Repository shape**
   - This is a **monorepo** with two major runtime components:
     - a **Flutter client** in `lib/` (plus `web/` for web hosting assets),
     - a **Dart server** in `server/`.
   - The architecture is a classic **UI client + HTTP API backend** split, with shared business concepts mirrored on both sides.

2. **Flutter application entry and shell**
   - The client starts in `lib/main.dart`, which wires the app into `lib/app/app.dart`.
   - `lib/app/router/app_router.dart` owns navigation/routing.
   - `lib/core/widgets/app_shell.dart` suggests a shared application frame/layout used across pages, while `lib/core/theme/app_theme.dart` centralizes styling.

3. **Client-side layering**
   - The Flutter code is organized into:
     - `core/` for cross-cutting concerns,
     - `features/` for business capabilities.
   - Each feature is further split into:
     - `data/repositories` for API/data access,
     - `domain/models` for typed business objects,
     - `presentation/pages` and `presentation/providers` for UI and state.

4. **Client cross-cutting infrastructure**
   - `lib/core/network/api_client.dart` and `api_exception.dart` form the shared HTTP/error boundary for all features.
   - `lib/core/storage/session_storage.dart` indicates persisted session/auth state on the client.
   - `lib/core/constants/api_constants.dart` holds API endpoints or route constants.
   - `lib/core/utils/json_parsers.dart` suggests centralized serialization/deserialization helpers.

5. **Client feature set**
   - The main product areas represented on the app are:
     - **Auth**: login/register/forgot password
     - **Catalog**: brands, categories, products, comparison, product details
     - **Cart**
     - **Favorites**
     - **Orders**
     - **Profile**
     - **Reviews**
     - **Admin**
   - This implies the client supports both consumer flows and privileged admin workflows in the same app.

6. **Client data flow**
   - UI pages call into feature providers, which in turn use repositories.
   - Repositories use the shared `ApiClient` to talk to the backend.
   - Domain models like `Product`, `CartItem`, `OrderDetails`, `UserProfile`, and `AuthSession` act as the typed data contract inside the app.
   - Session data is likely stored locally via `session_storage.dart` and reused by authenticated requests.

7. **Backend runtime and entry point**
   - The server is a separate Dart application launched from `server/bin/server.dart`.
   - `server/lib/src/router/app_router.dart` appears to define the HTTP route table.
   - This backend exposes feature-specific endpoints that correspond closely to the Flutter features.

8. **Backend request handling structure**
   - The server organizes logic by handler modules under `server/lib/src/handlers/`.
   - Each handler maps to a business area such as:
     - `auth`, `product`, `category`, `brand`,
     - `cart`, `favorites`, `order`, `review`,
     - `profile`, `address`,
     - `admin`, `compare`, `delivery`, `payment`, `system`.
   - This points to a layered backend where routing delegates to handlers, and handlers encapsulate request/response logic.

9. **Backend auth boundary**
   - Authentication is implemented explicitly in `server/lib/src/auth/` with:
     - `auth_handler.dart`,
     - `auth_service.dart`,
     - `auth_middleware.dart`,
     - `user_context.dart`.
   - The middleware indicates protected routes and request-scoped user identity/role propagation.
   - The presence of client `user_role.dart` and server auth middleware suggests role-based access, especially for admin paths.

10. **Backend infrastructure and integrations**
   - `server/lib/src/database/database_service.dart` is the backend’s data access boundary, likely connecting the handlers to a persistent database.
   - `server/lib/src/services/email_service.dart` is the main external integration visible in the tree, likely used for password recovery or notifications.
   - `server/lib/src/config/app_env.dart` shows environment-driven configuration, with `.env` in the server root.

11. **Data contract and serialization**
   - `server/lib/src/common/json_response.dart` and `request_body.dart` suggest standardized response wrapping and request parsing.
   - The client’s domain models and the server’s handlers are probably aligned around JSON payloads for entities such as products, orders, profiles, and reviews.

12. **Domain boundaries mirrored across client and server**
   - Several concepts exist on both sides, which is useful for drawing the architecture:
     - **Catalog**: brands/categories/products/characteristics
     - **Commerce**: cart/orders/payment/delivery
     - **Account**: auth/profile/address
     - **User engagement**: favorites/reviews
     - **Administration**: admin dashboard and service panels
   - This indicates a backend-for-frontend style API where each client feature maps to a server handler.

13. **Web deployment assets**
   - `web/index.html` and `web/manifest.json` indicate the Flutter client is also built for the web.
   - `web/icons/` contains browser/PWA assets, so the frontend is intended to run in a browser as well as other Flutter targets.

14. **Operational artifacts**
   - `server/backups/backup_2026-04-03T07-03-06-542037.sql` suggests the server has a real database persistence layer and that backups are part of the operational workflow.
   - The presence of both client and server lockfiles implies the repo is designed to be built and run independently per component.

15. **What to diagram**
   - A clean architecture diagram should show:
     - Flutter UI pages/providers at the edge,
     - feature repositories as the client-side data boundary,
     - shared client network/session/storage utilities underneath,
     - an HTTP API boundary to the Dart server,
     - server router → handlers → auth middleware/service → database/email services.
   - The most important external boundary is the **database**, with **email** as the other visible integration.

Main entry points: [`lib/core/network/api_client.dart`](https://github.com/ovtsunova/appliance_store/blob/master/lib/core/network/api_client.dart) (API client), [`lib/app/router/app_router.dart`](https://github.com/ovtsunova/appliance_store/blob/master/lib/app/router/app_router.dart) (Route setup), [`server/lib/src/router/app_router.dart`](https://github.com/ovtsunova/appliance_store/blob/master/server/lib/src/router/app_router.dart) (API router), [`lib/app/app.dart`](https://github.com/ovtsunova/appliance_store/blob/master/lib/app/app.dart) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Flutter client"]
  node_main["App entry<br/>Flutter entry<br/>[main.dart]"]
  node_app["App shell<br/>Flutter app<br/>[app.dart]"]
  node_router["Route setup<br/>navigation<br/>[app_router.dart]"]
  node_shell["Shell UI<br/>layout<br/>[app_shell.dart]"]
  node_theme["Theme<br/>design system<br/>[app_theme.dart]"]
  node_api_client["API client<br/>http boundary<br/>[api_client.dart]"]
  node_session["Session store<br/>local storage"]
  node_auth_feat["Auth<br/>feature"]
  node_catalog_feat["Catalog<br/>feature"]
  node_cart_feat["Cart<br/>feature"]
  node_orders_feat["Orders<br/>feature"]
  node_profile_feat["Profile<br/>feature"]
  node_admin_feat["Admin<br/>feature"]
end

subgraph group_server["Dart server"]
  node_server_entry["Server entry<br/>Dart server<br/>[server.dart]"]
  node_server_router["API router<br/>routing<br/>[app_router.dart]"]
  node_auth_srv["Auth stack"]
  node_handlers["Handlers"]
  node_db[("Database<br/>persistence")]
  node_email["Email service<br/>integration<br/>[email_service.dart]"]
  node_response["JSON contract<br/>serialization<br/>[json_response.dart]"]
end

subgraph group_web["Web assets"]
  node_web_assets["Web assets<br/>PWA assets<br/>[index.html]"]
end

node_main -->|"boots"| node_app
node_app -->|"uses"| node_router
node_app -->|"wraps"| node_shell
node_app -->|"applies"| node_theme
node_router -->|"routes"| node_auth_feat
node_router -->|"routes"| node_catalog_feat
node_router -->|"routes"| node_cart_feat
node_router -->|"routes"| node_orders_feat
node_router -->|"routes"| node_profile_feat
node_router -->|"routes"| node_admin_feat
node_auth_feat -->|"calls"| node_api_client
node_catalog_feat -->|"calls"| node_api_client
node_cart_feat -->|"calls"| node_api_client
node_orders_feat -->|"calls"| node_api_client
node_profile_feat -->|"calls"| node_api_client
node_admin_feat -->|"calls"| node_api_client
node_api_client -->|"reads/writes"| node_session
node_api_client -->|"http"| node_server_router
node_server_entry -->|"starts"| node_server_router
node_server_router -->|"protects"| node_auth_srv
node_server_router -->|"dispatches"| node_handlers
node_handlers -->|"formats"| node_response
node_auth_srv -->|"reads/writes"| node_db
node_handlers -->|"reads/writes"| node_db
node_auth_srv -->|"sends"| node_email
node_server_router -->|"uses"| node_response
node_web_assets -->|"hosts"| node_main

click node_main "https://github.com/ovtsunova/appliance_store/blob/master/lib/main.dart"
click node_app "https://github.com/ovtsunova/appliance_store/blob/master/lib/app/app.dart"
click node_router "https://github.com/ovtsunova/appliance_store/blob/master/lib/app/router/app_router.dart"
click node_shell "https://github.com/ovtsunova/appliance_store/blob/master/lib/core/widgets/app_shell.dart"
click node_theme "https://github.com/ovtsunova/appliance_store/blob/master/lib/core/theme/app_theme.dart"
click node_api_client "https://github.com/ovtsunova/appliance_store/blob/master/lib/core/network/api_client.dart"
click node_session "https://github.com/ovtsunova/appliance_store/blob/master/lib/core/storage/session_storage.dart"
click node_auth_feat "https://github.com/ovtsunova/appliance_store/tree/master/lib/features/auth"
click node_catalog_feat "https://github.com/ovtsunova/appliance_store/tree/master/lib/features/catalog"
click node_cart_feat "https://github.com/ovtsunova/appliance_store/tree/master/lib/features/cart"
click node_orders_feat "https://github.com/ovtsunova/appliance_store/tree/master/lib/features/orders"
click node_profile_feat "https://github.com/ovtsunova/appliance_store/tree/master/lib/features/profile"
click node_admin_feat "https://github.com/ovtsunova/appliance_store/tree/master/lib/features/admin"
click node_server_entry "https://github.com/ovtsunova/appliance_store/blob/master/server/bin/server.dart"
click node_server_router "https://github.com/ovtsunova/appliance_store/blob/master/server/lib/src/router/app_router.dart"
click node_auth_srv "https://github.com/ovtsunova/appliance_store/tree/master/server/lib/src/auth"
click node_handlers "https://github.com/ovtsunova/appliance_store/tree/master/server/lib/src/handlers"
click node_db "https://github.com/ovtsunova/appliance_store/blob/master/server/lib/src/database/database_service.dart"
click node_email "https://github.com/ovtsunova/appliance_store/blob/master/server/lib/src/services/email_service.dart"
click node_response "https://github.com/ovtsunova/appliance_store/blob/master/server/lib/src/common/json_response.dart"
click node_web_assets "https://github.com/ovtsunova/appliance_store/blob/master/web/index.html"

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_main,node_app,node_router,node_shell,node_theme,node_api_client,node_session,node_auth_feat,node_catalog_feat,node_cart_feat,node_orders_feat,node_profile_feat,node_admin_feat toneBlue
class node_server_entry,node_server_router,node_auth_srv,node_handlers,node_db,node_email,node_response toneAmber
class node_web_assets toneMint
```

## Components

### Flutter client

Mobile/web UI, shared app infrastructure, and feature modules.

- [App entry](https://github.com/ovtsunova/appliance_store/blob/master/lib/main.dart): Flutter entry · Bootstraps the client app. · `lib/main.dart`
- [App shell](https://github.com/ovtsunova/appliance_store/blob/master/lib/app/app.dart): Flutter app · Top-level app wiring and composition. · `lib/app/app.dart`
- [Route setup](https://github.com/ovtsunova/appliance_store/blob/master/lib/app/router/app_router.dart): navigation · Client navigation and page routing. · `lib/app/router/app_router.dart`
- [Shell UI](https://github.com/ovtsunova/appliance_store/blob/master/lib/core/widgets/app_shell.dart): layout · Shared application frame and page scaffolding. · `lib/core/widgets/app_shell.dart`
- [Theme](https://github.com/ovtsunova/appliance_store/blob/master/lib/core/theme/app_theme.dart): design system · Central app styling and visual tokens. · `lib/core/theme/app_theme.dart`
- [API client](https://github.com/ovtsunova/appliance_store/blob/master/lib/core/network/api_client.dart): http boundary · Shared HTTP access used by feature repositories. · `lib/core/network/api_client.dart`
- [Session store](https://github.com/ovtsunova/appliance_store/blob/master/lib/core/storage/session_storage.dart): local storage · Persisted client session and auth state. · `lib/core/storage/session_storage.dart`
- [Auth](https://github.com/ovtsunova/appliance_store/tree/master/lib/features/auth): feature · Login, registration, and password recovery. · `lib/features/auth`
- [Catalog](https://github.com/ovtsunova/appliance_store/tree/master/lib/features/catalog): feature · Brands, categories, products, and comparison. · `lib/features/catalog`
- [Cart](https://github.com/ovtsunova/appliance_store/tree/master/lib/features/cart): feature · Shopping cart management. · `lib/features/cart`
- [Orders](https://github.com/ovtsunova/appliance_store/tree/master/lib/features/orders): feature · Order summaries and order details. · `lib/features/orders`
- [Profile](https://github.com/ovtsunova/appliance_store/tree/master/lib/features/profile): feature · User profile and addresses. · `lib/features/profile`
- [Admin](https://github.com/ovtsunova/appliance_store/tree/master/lib/features/admin): feature · Administrative dashboard and service actions. · `lib/features/admin`

### Dart server

HTTP API, auth, handlers, and persistence/integrations.

- [Server entry](https://github.com/ovtsunova/appliance_store/blob/master/server/bin/server.dart): Dart server · Launches the HTTP backend. · `server/bin/server.dart`
- [API router](https://github.com/ovtsunova/appliance_store/blob/master/server/lib/src/router/app_router.dart): routing · Defines backend HTTP routes. · `server/lib/src/router/app_router.dart`
- [Auth stack](https://github.com/ovtsunova/appliance_store/tree/master/server/lib/src/auth): auth · Authentication handler, service, middleware, and user context. · `server/lib/src/auth`
- [Handlers](https://github.com/ovtsunova/appliance_store/tree/master/server/lib/src/handlers): request handlers · Feature-oriented backend request handlers. · `server/lib/src/handlers`
- [Database](https://github.com/ovtsunova/appliance_store/blob/master/server/lib/src/database/database_service.dart): persistence · Persistent data access boundary. · `server/lib/src/database/database_service.dart`
- [Email service](https://github.com/ovtsunova/appliance_store/blob/master/server/lib/src/services/email_service.dart): integration · Outbound email integration for recovery and notifications. · `server/lib/src/services/email_service.dart`
- [JSON contract](https://github.com/ovtsunova/appliance_store/blob/master/server/lib/src/common/json_response.dart): serialization · Standard response wrapping and request body parsing. · `server/lib/src/common/json_response.dart`

### Web assets

Browser/PWA hosting assets for the Flutter client.

- [Web assets](https://github.com/ovtsunova/appliance_store/blob/master/web/index.html): PWA assets · Browser entrypoint and manifest assets. · `web/index.html`

## Connections

- App entry → App shell: boots · Main initializes the application shell.
- App shell → Route setup: uses · App composition includes navigation setup.
- App shell → Shell UI: wraps · Shared shell frames pages.
- App shell → Theme: applies · App uses centralized theme definitions.
- Route setup → Auth: routes · Navigation exposes auth pages.
- Route setup → Catalog: routes · Navigation exposes catalog pages.
- Route setup → Cart: routes · Navigation exposes cart pages.
- Route setup → Orders: routes · Navigation exposes order pages.
- Route setup → Profile: routes · Navigation exposes profile pages.
- Route setup → Admin: routes · Navigation exposes admin pages.
- Auth → API client: calls · Feature repositories use the shared API client.
- Catalog → API client: calls · Feature repositories use the shared API client.
- Cart → API client: calls · Feature repositories use the shared API client.
- Orders → API client: calls · Feature repositories use the shared API client.
- Profile → API client: calls · Feature repositories use the shared API client.
- Admin → API client: calls · Feature repositories use the shared API client.
- API client → Session store: reads/writes · API client reuses persisted session state for authenticated requests.
- API client → API router: http · Client requests hit the backend API routes.
- Server entry → API router: starts · Server entry initializes routing.
- API router → Auth stack: protects · Router delegates auth-sensitive paths through auth middleware/service.
- API router → Handlers: dispatches · Routes delegate to feature handlers.
- Handlers → JSON contract: formats · Handlers use shared request/response helpers.
- Auth stack → Database: reads/writes · Auth resolves users and sessions through persistence.
- Handlers → Database: reads/writes · Business handlers persist and query domain data.
- Auth stack → Email service: sends · Auth flows can trigger outbound email.
- API router → JSON contract: uses · API endpoints share standard JSON contract utilities.
- Web assets → App entry: hosts · Web assets host the Flutter client build.
