How kernphilipp/gated works
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: navbar.dart Navigation · server.dart Backend server · app.dart App shell · kennzeichen_view.dart Kennzeichen
Components 24
Flutter client
Cross-platform user-facing app and UI flow.
- App bootstrap · Initial app composition, theme, and config setup.
gated/lib/main.dart - App shell · Top-level app widget and theming boundary.
gated/lib/app/app.dart - Config · Centralized application configuration and environment selection.
gated/lib/config/app_config.dart - Auth screens · Login and registration entry points.
gated/lib/screens/login_screen.dart - Home screen · Main post-login screen that hosts the primary views.
gated/lib/screens/home_screen.dart - Navigation · Top-level in-app navigation and item model.
gated/lib/features/navbar/navbar.dart - Dashboard · Primary overview surface shown inside the app shell.
gated/lib/views/dashboard_view.dart - Profile · User profile surface.
gated/lib/views/profile_view.dart - Settings · Application settings surface.
gated/lib/views/settings_view.dart - Kennzeichen · License-plate management area with table-based workflow.
gated/lib/views/kennzeichen_view.dart - Data table · Central grid for browsing and editing records.
gated/lib/views/kennzeichen/kennzeichen_data_table.dart - Row control · Row state and controller logic for table interactions.
gated/lib/views/kennzeichen/kennzeichen_rows_controller.dart - Edit dialog · Modal editing flow for record changes.
gated/lib/views/kennzeichen/kennzeichen_edit_dialog.dart - Auth service · Client-side authentication boundary for the Flutter app.
gated/lib/services/auth_service.dart - Kennzeichen service · 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 · Dart backend entry point and process bootstrap.
gated/backend/server.dart - Auth routes · Authentication endpoints exposed by the backend.
gated/backend/lib/routes/auth_routes.dart - Kennzeichen routes · License-plate endpoints exposed by the backend.
gated/backend/lib/routes/kennzeichen_routes.dart - Auth core · Hashing, JWT handling, allowlist checks, and request auth.
gated/backend/lib/auth/jwt_service.dart - Database layer · Database abstraction and license-plate persistence boundary.
gated/backend/lib/db/database.dart - CORS middleware · Central cross-origin request policy.
gated/backend/lib/middleware/cors.dart
Deployment
Raspberry Pi packaging and service runtime.
- Release pipeline · Build and release automation for deployable artifacts.
.github/workflows/release.yml - Packaging · Builds the release package and prepares deployment inputs.
deploy/build_release_package.sh - Pi services · Managed backend and deploy timer/services for Raspberry Pi.
deploy/gated-backend.service
Connections 25
- 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.