How ovtsunova/appliance_store works
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: api_client.dart API client · router/app_router.dart Route setup · router/app_router.dart API router · app.dart App shell
Components 21
Flutter client
Mobile/web UI, shared app infrastructure, and feature modules.
- App entry · Bootstraps the client app.
lib/main.dart - App shell · Top-level app wiring and composition.
lib/app/app.dart - Route setup · Client navigation and page routing.
lib/app/router/app_router.dart - Shell UI · Shared application frame and page scaffolding.
lib/core/widgets/app_shell.dart - Theme · Central app styling and visual tokens.
lib/core/theme/app_theme.dart - API client · Shared HTTP access used by feature repositories.
lib/core/network/api_client.dart - Session store · Persisted client session and auth state.
lib/core/storage/session_storage.dart - Auth · Login, registration, and password recovery.
lib/features/auth - Catalog · Brands, categories, products, and comparison.
lib/features/catalog - Cart · Shopping cart management.
lib/features/cart - Orders · Order summaries and order details.
lib/features/orders - Profile · User profile and addresses.
lib/features/profile - Admin · Administrative dashboard and service actions.
lib/features/admin
Dart server
HTTP API, auth, handlers, and persistence/integrations.
- Server entry · Launches the HTTP backend.
server/bin/server.dart - API router · Defines backend HTTP routes.
server/lib/src/router/app_router.dart - Auth stack · Authentication handler, service, middleware, and user context.
server/lib/src/auth - Handlers · Feature-oriented backend request handlers.
server/lib/src/handlers - Database · Persistent data access boundary.
server/lib/src/database/database_service.dart - Email service · Outbound email integration for recovery and notifications.
server/lib/src/services/email_service.dart - JSON contract · 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 · Browser entrypoint and manifest assets.
web/index.html
Connections 27
- 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.