# kernphilipp/gated architecture

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

- Interactive diagram: https://gitdiagram.com/kernphilipp/gated
- Repository: https://github.com/kernphilipp/gated

## Overview

1. **System shape**
   - GATED is a **Flutter client + Dart backend** system. The Flutter app is the user-facing product; the backend exposes API endpoints for authentication and license-plate-related data, and the repo includes deployment tooling for a **Raspberry Pi** target.

2. **Cross-platform frontend shell**
   - The Flutter app lives under `gated/lib` and is packaged for **Android, iOS, web, Linux, macOS, and Windows**.
   - Core app composition is in `main.dart`, `app/app.dart`, `app/theme.dart`, and `config/app_config.dart`, which suggests a centralized app bootstrap, theming, and environment/config boundary.

3. **Navigation and top-level screens**
   - The main user flow is organized around `screens/` and `views/`.
   - Primary screens include `login_screen.dart`, `register_screen.dart`, and `home_screen.dart`.
   - In-app navigation is handled by `features/navbar/` and the main content surfaces are split into `dashboard_view.dart`, `profile_view.dart`, `settings_view.dart`, and `kennzeichen_view.dart`.

4. **Authentication boundary**
   - Client-side auth is handled by `services/auth_service.dart`.
   - Supporting UI behavior under `features/auth/` includes session expiration handling and autofill/focus recovery, which indicates the app manages token/session lifecycle explicitly on the client.
   - On the backend, auth logic is separated into `lib/auth/` with hashing, JWT handling, request authentication, and an allowlist.

5. **Kennzeichen domain flow**
   - The “Kennzeichen” area is a dedicated business module for license-plate data management.
   - The Flutter side has a fairly rich UI split into table, row, filter/sort, edit dialog, controller, and action components under `views/kennzeichen/`.
   - This suggests a data-grid style workflow: fetch records, filter/sort them, edit rows in dialogs, and apply actions from the table UI.

6. **Client-to-server service layer**
   - `services/kennzeichen_service.dart` is the client API boundary for the Kennzeichen feature.
   - The app’s views do not appear to talk to persistence directly; they go through service classes, which keeps backend communication isolated from the UI layer.

7. **Backend API structure**
   - The backend entry point is `backend/server.dart`.
   - Routing is split by concern: `routes/auth_routes.dart` and `routes/kennzeichen_routes.dart`.
   - Cross-cutting HTTP behavior is isolated in `middleware/cors.dart`, so API access policy is handled centrally rather than in individual handlers.

8. **Persistence and data access**
   - Backend database access is separated into `db/database.dart` and `db/license_plate_database.dart`.
   - This indicates a layered backend: route handlers call auth/data services, which then use a database abstraction instead of embedding storage logic in the routes.
   - The repository tree does not show a specific database engine, so the important architectural point is the **storage boundary**, not the underlying engine.

9. **Security model**
   - Authentication is JWT-based on the backend, with password hashing and a request-auth middleware layer.
   - The presence of an allowlist suggests some operations or users are explicitly permitted, so authorization is not only token-based but also policy-gated.

10. **Deployment and operations**
   - `deploy/` contains the production packaging and installation path: release-building script, environment templates, systemd service units, and a timer.
   - `deploy/README.md` and the service files indicate the backend is intended to run as a managed Linux service on a Raspberry Pi, with config supplied via env files.

11. **Release automation**
   - `.github/workflows/release.yml` plus `deploy/build_release_package.sh` suggest a formal release pipeline that produces deployable artifacts rather than relying on manual builds.
   - This is the main CI/CD boundary in the repo.

12. **What to draw in an architecture diagram**
   - Draw the **Flutter client** as the presentation layer.
   - Draw the **Dart backend** as a separate API/service layer with auth and Kennzeichen endpoints.
   - Put **database/persistence** behind the backend.
   - Add a separate **deployment/ops lane** for Raspberry Pi release packaging, systemd service execution, and scheduled deployment automation.

Main entry points: [`gated/lib/features/navbar/navbar.dart`](https://github.com/kernphilipp/gated/blob/main/gated/lib/features/navbar/navbar.dart) (Navigation), [`gated/backend/server.dart`](https://github.com/kernphilipp/gated/blob/main/gated/backend/server.dart) (Backend server), [`gated/lib/app/app.dart`](https://github.com/kernphilipp/gated/blob/main/gated/lib/app/app.dart) (App shell), [`gated/lib/views/kennzeichen_view.dart`](https://github.com/kernphilipp/gated/blob/main/gated/lib/views/kennzeichen_view.dart) (Kennzeichen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Flutter client"]
  node_main_bootstrap["App bootstrap<br/>Flutter entry<br/>[main.dart]"]
  node_app_shell["App shell<br/>UI composition<br/>[app.dart]"]
  node_app_config["Config<br/>[app_config.dart]"]
  node_auth_screens["Auth screens<br/>[login_screen.dart]"]
  node_home_screen["Home screen<br/>Screen host<br/>[home_screen.dart]"]
  node_navbar["Navigation<br/>Nav shell<br/>[navbar.dart]"]
  node_dashboard_view["Dashboard<br/>View"]
  node_profile_view["Profile<br/>View<br/>[profile_view.dart]"]
  node_settings_view["Settings<br/>View<br/>[settings_view.dart]"]
  node_kennzeichen_view["Kennzeichen<br/>Domain view"]
  node_kennzeichen_table["Data table<br/>Table UI"]
  node_kennzeichen_rows["Row control<br/>Table logic"]
  node_kennzeichen_dialog["Edit dialog<br/>Editor UI"]
  node_auth_service["Auth service<br/>API client<br/>[auth_service.dart]"]
  node_kennzeichen_service["Kennzeichen service<br/>API client"]
end

subgraph group_server["Dart backend"]
  node_backend_server["Backend server<br/>API entry<br/>[server.dart]"]
  node_auth_routes["Auth routes<br/>HTTP routes<br/>[auth_routes.dart]"]
  node_kennzeichen_routes["Kennzeichen routes<br/>HTTP routes"]
  node_auth_core["Auth core<br/>Security layer<br/>[jwt_service.dart]"]
  node_db_layer[("Database layer<br/>Storage access<br/>[database.dart]")]
  node_cors_middleware["CORS middleware<br/>HTTP middleware<br/>[cors.dart]"]
end

subgraph group_ops["Deployment"]
  node_release_pipeline["Release pipeline<br/>CI/CD<br/>[release.yml]"]
  node_deploy_packaging["Packaging<br/>Release script"]
  node_pi_services["Pi services<br/>Systemd runtime"]
end

node_main_bootstrap -->|"boots"| node_app_shell
node_main_bootstrap -->|"loads"| node_app_config
node_app_shell -->|"routes to"| node_auth_screens
node_app_shell -->|"hosts"| node_home_screen
node_home_screen -->|"navigates"| node_navbar
node_navbar -->|"opens"| node_dashboard_view
node_navbar -->|"opens"| node_profile_view
node_navbar -->|"opens"| node_settings_view
node_navbar -->|"opens"| node_kennzeichen_view
node_kennzeichen_view -->|"renders"| node_kennzeichen_table
node_kennzeichen_table -->|"uses"| node_kennzeichen_rows
node_kennzeichen_table -->|"edits via"| node_kennzeichen_dialog
node_auth_screens -->|"calls"| node_auth_service
node_kennzeichen_view -->|"calls"| node_kennzeichen_service
node_auth_service -->|"requests"| node_backend_server
node_kennzeichen_service -->|"requests"| node_backend_server
node_backend_server -->|"exposes"| node_auth_routes
node_backend_server -->|"exposes"| node_kennzeichen_routes
node_auth_routes -->|"uses"| node_auth_core
node_kennzeichen_routes -->|"reads/writes"| node_db_layer
node_auth_routes -->|"passes through"| node_cors_middleware
node_kennzeichen_routes -->|"passes through"| node_cors_middleware
node_release_pipeline -->|"builds"| node_deploy_packaging
node_deploy_packaging -->|"installs"| node_pi_services
node_pi_services -->|"runs"| node_backend_server

click node_main_bootstrap "https://github.com/kernphilipp/gated/blob/main/gated/lib/main.dart"
click node_app_shell "https://github.com/kernphilipp/gated/blob/main/gated/lib/app/app.dart"
click node_app_config "https://github.com/kernphilipp/gated/blob/main/gated/lib/config/app_config.dart"
click node_auth_screens "https://github.com/kernphilipp/gated/blob/main/gated/lib/screens/login_screen.dart"
click node_home_screen "https://github.com/kernphilipp/gated/blob/main/gated/lib/screens/home_screen.dart"
click node_navbar "https://github.com/kernphilipp/gated/blob/main/gated/lib/features/navbar/navbar.dart"
click node_dashboard_view "https://github.com/kernphilipp/gated/blob/main/gated/lib/views/dashboard_view.dart"
click node_profile_view "https://github.com/kernphilipp/gated/blob/main/gated/lib/views/profile_view.dart"
click node_settings_view "https://github.com/kernphilipp/gated/blob/main/gated/lib/views/settings_view.dart"
click node_kennzeichen_view "https://github.com/kernphilipp/gated/blob/main/gated/lib/views/kennzeichen_view.dart"
click node_kennzeichen_table "https://github.com/kernphilipp/gated/blob/main/gated/lib/views/kennzeichen/kennzeichen_data_table.dart"
click node_kennzeichen_rows "https://github.com/kernphilipp/gated/blob/main/gated/lib/views/kennzeichen/kennzeichen_rows_controller.dart"
click node_kennzeichen_dialog "https://github.com/kernphilipp/gated/blob/main/gated/lib/views/kennzeichen/kennzeichen_edit_dialog.dart"
click node_auth_service "https://github.com/kernphilipp/gated/blob/main/gated/lib/services/auth_service.dart"
click node_kennzeichen_service "https://github.com/kernphilipp/gated/blob/main/gated/lib/services/kennzeichen_service.dart"
click node_backend_server "https://github.com/kernphilipp/gated/blob/main/gated/backend/server.dart"
click node_auth_routes "https://github.com/kernphilipp/gated/blob/main/gated/backend/lib/routes/auth_routes.dart"
click node_kennzeichen_routes "https://github.com/kernphilipp/gated/blob/main/gated/backend/lib/routes/kennzeichen_routes.dart"
click node_auth_core "https://github.com/kernphilipp/gated/blob/main/gated/backend/lib/auth/jwt_service.dart"
click node_db_layer "https://github.com/kernphilipp/gated/blob/main/gated/backend/lib/db/database.dart"
click node_cors_middleware "https://github.com/kernphilipp/gated/blob/main/gated/backend/lib/middleware/cors.dart"
click node_release_pipeline "https://github.com/kernphilipp/gated/blob/main/.github/workflows/release.yml"
click node_deploy_packaging "https://github.com/kernphilipp/gated/blob/main/deploy/build_release_package.sh"
click node_pi_services "https://github.com/kernphilipp/gated/blob/main/deploy/gated-backend.service"

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_bootstrap,node_app_shell,node_app_config,node_auth_screens,node_home_screen,node_navbar,node_dashboard_view,node_profile_view,node_settings_view,node_kennzeichen_view,node_kennzeichen_table,node_kennzeichen_rows,node_kennzeichen_dialog,node_auth_service,node_kennzeichen_service toneBlue
class node_backend_server,node_auth_routes,node_kennzeichen_routes,node_auth_core,node_db_layer,node_cors_middleware toneAmber
class node_release_pipeline,node_deploy_packaging,node_pi_services toneMint
```

## Components

### Flutter client

Cross-platform user-facing app and UI flow.

- [App bootstrap](https://github.com/kernphilipp/gated/blob/main/gated/lib/main.dart): Flutter entry · Initial app composition, theme, and config setup. · `gated/lib/main.dart`
- [App shell](https://github.com/kernphilipp/gated/blob/main/gated/lib/app/app.dart): UI composition · Top-level app widget and theming boundary. · `gated/lib/app/app.dart`
- [Config](https://github.com/kernphilipp/gated/blob/main/gated/lib/config/app_config.dart): Environment config · Centralized application configuration and environment selection. · `gated/lib/config/app_config.dart`
- [Auth screens](https://github.com/kernphilipp/gated/blob/main/gated/lib/screens/login_screen.dart): Screens · Login and registration entry points. · `gated/lib/screens/login_screen.dart`
- [Home screen](https://github.com/kernphilipp/gated/blob/main/gated/lib/screens/home_screen.dart): Screen host · Main post-login screen that hosts the primary views. · `gated/lib/screens/home_screen.dart`
- [Navigation](https://github.com/kernphilipp/gated/blob/main/gated/lib/features/navbar/navbar.dart): Nav shell · Top-level in-app navigation and item model. · `gated/lib/features/navbar/navbar.dart`
- [Dashboard](https://github.com/kernphilipp/gated/blob/main/gated/lib/views/dashboard_view.dart): View · Primary overview surface shown inside the app shell. · `gated/lib/views/dashboard_view.dart`
- [Profile](https://github.com/kernphilipp/gated/blob/main/gated/lib/views/profile_view.dart): View · User profile surface. · `gated/lib/views/profile_view.dart`
- [Settings](https://github.com/kernphilipp/gated/blob/main/gated/lib/views/settings_view.dart): View · Application settings surface. · `gated/lib/views/settings_view.dart`
- [Kennzeichen](https://github.com/kernphilipp/gated/blob/main/gated/lib/views/kennzeichen_view.dart): Domain view · License-plate management area with table-based workflow. · `gated/lib/views/kennzeichen_view.dart`
- [Data table](https://github.com/kernphilipp/gated/blob/main/gated/lib/views/kennzeichen/kennzeichen_data_table.dart): Table UI · Central grid for browsing and editing records. · `gated/lib/views/kennzeichen/kennzeichen_data_table.dart`
- [Row control](https://github.com/kernphilipp/gated/blob/main/gated/lib/views/kennzeichen/kennzeichen_rows_controller.dart): Table logic · Row state and controller logic for table interactions. · `gated/lib/views/kennzeichen/kennzeichen_rows_controller.dart`
- [Edit dialog](https://github.com/kernphilipp/gated/blob/main/gated/lib/views/kennzeichen/kennzeichen_edit_dialog.dart): Editor UI · Modal editing flow for record changes. · `gated/lib/views/kennzeichen/kennzeichen_edit_dialog.dart`
- [Auth service](https://github.com/kernphilipp/gated/blob/main/gated/lib/services/auth_service.dart): API client · Client-side authentication boundary for the Flutter app. · `gated/lib/services/auth_service.dart`
- [Kennzeichen service](https://github.com/kernphilipp/gated/blob/main/gated/lib/services/kennzeichen_service.dart): API client · Client-side service boundary for license-plate data operations. · `gated/lib/services/kennzeichen_service.dart`

### Dart backend

API, auth, and data access services.

- [Backend server](https://github.com/kernphilipp/gated/blob/main/gated/backend/server.dart): API entry · Dart backend entry point and process bootstrap. · `gated/backend/server.dart`
- [Auth routes](https://github.com/kernphilipp/gated/blob/main/gated/backend/lib/routes/auth_routes.dart): HTTP routes · Authentication endpoints exposed by the backend. · `gated/backend/lib/routes/auth_routes.dart`
- [Kennzeichen routes](https://github.com/kernphilipp/gated/blob/main/gated/backend/lib/routes/kennzeichen_routes.dart): HTTP routes · License-plate endpoints exposed by the backend. · `gated/backend/lib/routes/kennzeichen_routes.dart`
- [Auth core](https://github.com/kernphilipp/gated/blob/main/gated/backend/lib/auth/jwt_service.dart): Security layer · Hashing, JWT handling, allowlist checks, and request auth. · `gated/backend/lib/auth/jwt_service.dart`
- [Database layer](https://github.com/kernphilipp/gated/blob/main/gated/backend/lib/db/database.dart): Storage access · Database abstraction and license-plate persistence boundary. · `gated/backend/lib/db/database.dart`
- [CORS middleware](https://github.com/kernphilipp/gated/blob/main/gated/backend/lib/middleware/cors.dart): HTTP middleware · Central cross-origin request policy. · `gated/backend/lib/middleware/cors.dart`

### Deployment

Raspberry Pi packaging and service runtime.

- [Release pipeline](https://github.com/kernphilipp/gated/blob/main/.github/workflows/release.yml): CI/CD · Build and release automation for deployable artifacts. · `.github/workflows/release.yml`
- [Packaging](https://github.com/kernphilipp/gated/blob/main/deploy/build_release_package.sh): Release script · Builds the release package and prepares deployment inputs. · `deploy/build_release_package.sh`
- [Pi services](https://github.com/kernphilipp/gated/blob/main/deploy/gated-backend.service): Systemd runtime · Managed backend and deploy timer/services for Raspberry Pi. · `deploy/gated-backend.service`

## Connections

- App bootstrap → App shell: boots · Main entry composes the app shell.
- App bootstrap → Config: loads · Bootstrap reads app configuration.
- App shell → Auth screens: routes to · App shell exposes login/register flows.
- App shell → Home screen: hosts · Authenticated session enters the home screen.
- Home screen → Navigation: navigates · Home screen uses the navigation shell.
- Navigation → Dashboard: opens · Navigation can show the dashboard.
- Navigation → Profile: opens · Navigation can show profile.
- Navigation → Settings: opens · Navigation can show settings.
- Navigation → Kennzeichen: opens · Navigation can show the Kennzeichen module.
- Kennzeichen → Data table: renders · Domain view centers on the data table.
- Data table → Row control: uses · Table delegates row state and actions.
- Data table → Edit dialog: edits via · Row edits open the modal dialog.
- Auth screens → Auth service: calls · Login and registration use auth API client logic.
- Kennzeichen → Kennzeichen service: calls · Domain UI communicates through the service layer.
- Auth service → Backend server: requests · Client auth calls the backend API.
- Kennzeichen service → Backend server: requests · Client domain data calls the backend API.
- Backend server → Auth routes: exposes · Backend wires authentication endpoints.
- Backend server → Kennzeichen routes: exposes · Backend wires Kennzeichen endpoints.
- Auth routes → Auth core: uses · Auth routes rely on JWT and request auth logic.
- Kennzeichen routes → Database layer: reads/writes · Domain routes persist through the storage layer.
- Auth routes → CORS middleware: passes through · HTTP requests are gated by shared CORS policy.
- Kennzeichen routes → CORS middleware: passes through · HTTP requests are gated by shared CORS policy.
- Release pipeline → Packaging: builds · Workflow produces release artifacts via packaging script.
- Packaging → Pi services: installs · Release output is prepared for systemd-based Pi runtime.
- Pi services → Backend server: runs · System services execute the backend on the target device.
