# sgbalda/verbandsbuch architecture

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

- Interactive diagram: https://gitdiagram.com/sgbalda/verbandsbuch
- Repository: https://github.com/sgbalda/verbandsbuch

## Overview

1. **Overall shape**
   - This is a single-repo full-stack safety documentation system.
   - The architecture is split into a **React/Vite client**, a **Node/Express/tRPC backend**, and a **PostgreSQL database** managed with **Drizzle migrations**.
   - The frontend and backend are strongly coupled through shared TypeScript types and tRPC procedures.

2. **Frontend application boundary**
   - `client/` contains the browser app built with **React + TypeScript + Vite**.
   - `client/src/pages` defines the main user-facing screens: home, first-aid reporting, hazardous-area reporting, updates, and admin pages.
   - `client/src/components` holds form widgets, admin panels, upload controls, and reusable UI primitives.

3. **User-facing workflows**
   - The public flow is centered on selecting a plant and submitting either a **first-aid case** or a **hazard report**.
   - The app supports optional photos, mobile camera capture, and timestamp helpers like “Now” buttons.
   - These flows likely create records through the backend and show validation/feedback in the UI.

4. **Admin and responsibility workflows**
   - Admin functionality is separated into dedicated pages such as `AdminDashboard` and `AdminLogin`.
   - Admin components include analytics, profile management, responsible-person lists, and daily action management.
   - The admin area is where safety staff review, evaluate, and manage follow-up actions across plants and areas.

5. **Backend application boundary**
   - `server/_core` contains the backend framework glue: context creation, routers, auth, admin auth, cookies, environment config, and the main tRPC wiring.
   - The server is responsible for business rules and access control; permissions are not enforced in the client.
   - `server/_core/vite.ts` suggests the server also integrates with the Vite app during development or SSR-style serving.

6. **API contract and data flow**
   - The client talks to the server primarily through **tRPC** (`client/src/lib/trpc.ts`, `server/_core/trpc.ts`).
   - This makes the API type-safe end-to-end and keeps request/response contracts aligned with shared TypeScript types.
   - The likely request path is: browser UI → tRPC client → server router/context → database/email/storage side effects → typed response back to UI.

7. **Shared domain layer**
   - `shared/` contains code intended to be reused by both client and server.
   - `shared/types.ts`, `shared/const.ts`, and `shared/_core/*` centralize domain types, constants, and shared utilities/errors.
   - This layer reduces drift between form validation, backend logic, and database-related domain values such as statuses, roles, and dropdown options.

8. **Database and schema management**
   - `drizzle/schema.ts`, `drizzle/relations.ts`, and the migration files define the persistent model.
   - The schema includes core entities mentioned in the README: first-aid services, hazardous areas, responsible persons, admins, dropdown options, audit logs, plants, and areas.
   - The presence of many migrations indicates the schema has evolved around multi-plant support, role assignments, and action tracking.

9. **File and media handling**
   - Uploaded media is stored under `uploads/`, which is part of the runtime filesystem rather than a separate object store.
   - The README notes photos can come from file upload or smartphone camera, so media handling is a first-class part of the reporting flow.
   - `nginx.conf` and the HTTPS setup script indicate deployment expects secure serving for camera access and cookies.

10. **Identity, roles, and permissions**
   - The system has distinct roles: **user**, **responsible person**, **admin**, and **superadmin**.
   - Access control is implemented server-side in the auth/admin router layer, not just in the UI.
   - Responsible users can update assigned actions; superadmins can manage admins, delete records, and maintain dropdown data.

11. **Notifications and operational side effects**
   - `server/_core/email-smtp.ts` shows SMTP-based outbound email is part of the backend.
   - Email notifications are used to alert responsible persons about assignments and likely overdue actions.
   - This makes the backend not only a CRUD API but also an event-driven notifier for operational follow-up.

12. **Analytics and reporting**
   - The admin UI includes analytics by location, category, and time range.
   - This implies server-side aggregation over first-aid and hazard records rather than purely client-side reporting.
   - Audit logging is also part of the persisted model, supporting traceability for safety and compliance.

13. **Runtime and deployment boundaries**
   - The repo is designed to be deployed behind a reverse proxy with HTTPS.
   - Runtime dependencies include **Node.js**, **PostgreSQL**, and **SMTP** infrastructure.
   - `setup-https.js`, `nginx.conf`, and the deployment guide suggest the app is meant to run as a secured internal business application.

14. **Diagram takeaway**
   - A good architecture diagram should show:
     - browser clients hitting the Vite-served React app,
     - the React app calling tRPC endpoints on the Node/Express server,
     - the server enforcing roles, writing to PostgreSQL via Drizzle, storing uploads locally, and sending emails via SMTP,
     - shared types/constants bridging frontend and backend,
     - admin-only paths branching off from the same backend but with stricter authorization.

Main entry points: [`server/_core/trpc.ts`](https://github.com/sgbalda/verbandsbuch/blob/master/server/_core/trpc.ts) (tRPC router), [`server/_core/context.ts`](https://github.com/sgbalda/verbandsbuch/blob/master/server/_core/context.ts) (Request context), [`client/src/App.tsx`](https://github.com/sgbalda/verbandsbuch/blob/master/client/src/App.tsx) (React app), [`client/src/pages`](https://github.com/sgbalda/verbandsbuch/tree/master/client/src/pages) (Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client app"]
  node_client_app["React app<br/>Vite client<br/>[App.tsx]"]
  node_client_pages["Pages<br/>screens"]
  node_client_components["UI components<br/>widgets"]
  node_client_trpc(("tRPC client<br/>api client<br/>[trpc.ts]"))
  node_client_contexts(("Language/theme<br/>state contexts"))
end

subgraph group_shared["Shared domain"]
  node_shared_types["Domain types<br/>shared types<br/>[types.ts]"]
  node_shared_consts["Constants<br/>[const.ts]"]
  node_shared_core["Shared core<br/>helpers"]
end

subgraph group_server["Server core"]
  node_server_entry["Server entry<br/>app bootstrap<br/>[index.ts]"]
  node_server_trpc(("tRPC router<br/>api router<br/>[trpc.ts]"))
  node_server_context(("Request context<br/>runtime context<br/>[context.ts]"))
  node_server_auth{{"Auth layer<br/>access control<br/>[auth-router.ts]"}}
  node_server_admin{{"Admin layer<br/>admin access<br/>[admin-router.ts]"}}
  node_server_email["SMTP mailer<br/>notification service<br/>[email-smtp.ts]"]
  node_server_vite["Vite bridge<br/>dev serving<br/>[vite.ts]"]
end

subgraph group_data["Persistence"]
  node_db_schema[("Schema<br/>[schema.ts]")]
  node_db_migrations["Migrations"]
  node_db_relations["Relations<br/>db mapping<br/>[relations.ts]"]
  node_uploads_store[("Uploads<br/>filesystem storage")]
end

node_client_app -->|"renders"| node_client_pages
node_client_app -->|"uses"| node_client_components
node_client_app -->|"wraps"| node_client_contexts
node_client_pages -->|"calls"| node_client_trpc
node_client_components -->|"submits"| node_client_trpc
node_client_trpc -->|"api contract"| node_server_trpc
node_client_pages -->|"uses"| node_shared_types
node_client_components -->|"uses"| node_shared_consts
node_server_entry -->|"mounts"| node_server_trpc
node_server_trpc -->|"builds on"| node_server_context
node_server_trpc -->|"protects"| node_server_auth
node_server_trpc -->|"protects"| node_server_admin
node_server_context -->|"queries"| node_db_schema
node_server_context -->|"joins"| node_db_relations
node_server_trpc -->|"notifies"| node_server_email
node_server_entry -->|"integrates"| node_server_vite
node_server_context -->|"stores media"| node_uploads_store
node_db_schema -->|"evolved by"| node_db_migrations
node_db_relations -->|"maps"| node_db_schema
node_shared_core -.->|"supports"| node_server_context
node_shared_core -.->|"supports"| node_client_app

click node_client_app "https://github.com/sgbalda/verbandsbuch/blob/master/client/src/App.tsx"
click node_client_pages "https://github.com/sgbalda/verbandsbuch/tree/master/client/src/pages"
click node_client_components "https://github.com/sgbalda/verbandsbuch/tree/master/client/src/components"
click node_client_trpc "https://github.com/sgbalda/verbandsbuch/blob/master/client/src/lib/trpc.ts"
click node_client_contexts "https://github.com/sgbalda/verbandsbuch/tree/master/client/src/contexts"
click node_shared_types "https://github.com/sgbalda/verbandsbuch/blob/master/shared/types.ts"
click node_shared_consts "https://github.com/sgbalda/verbandsbuch/blob/master/shared/const.ts"
click node_shared_core "https://github.com/sgbalda/verbandsbuch/tree/master/shared/_core"
click node_server_entry "https://github.com/sgbalda/verbandsbuch/blob/master/server/_core/index.ts"
click node_server_trpc "https://github.com/sgbalda/verbandsbuch/blob/master/server/_core/trpc.ts"
click node_server_context "https://github.com/sgbalda/verbandsbuch/blob/master/server/_core/context.ts"
click node_server_auth "https://github.com/sgbalda/verbandsbuch/blob/master/server/_core/auth-router.ts"
click node_server_admin "https://github.com/sgbalda/verbandsbuch/blob/master/server/_core/admin-router.ts"
click node_server_email "https://github.com/sgbalda/verbandsbuch/blob/master/server/_core/email-smtp.ts"
click node_server_vite "https://github.com/sgbalda/verbandsbuch/blob/master/server/_core/vite.ts"
click node_db_schema "https://github.com/sgbalda/verbandsbuch/blob/master/drizzle/schema.ts"
click node_db_migrations "https://github.com/sgbalda/verbandsbuch/tree/master/drizzle"
click node_db_relations "https://github.com/sgbalda/verbandsbuch/blob/master/drizzle/relations.ts"
click node_uploads_store "https://github.com/sgbalda/verbandsbuch/tree/master/uploads"

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_client_app,node_client_pages,node_client_components,node_client_trpc,node_client_contexts toneBlue
class node_shared_types,node_shared_consts,node_shared_core toneAmber
class node_server_entry,node_server_trpc,node_server_context,node_server_auth,node_server_admin,node_server_email,node_server_vite toneMint
class node_db_schema,node_db_migrations,node_db_relations,node_uploads_store toneRose
```

## Components

### Client app

React/Vite browser application and its UI workflow layer.

- [React app](https://github.com/sgbalda/verbandsbuch/blob/master/client/src/App.tsx): Vite client · Browser-facing application shell and route composition. · `client/src/App.tsx`
- [Pages](https://github.com/sgbalda/verbandsbuch/tree/master/client/src/pages): screens · Home, reporting, updates, and admin screens. · `client/src/pages`
- [UI components](https://github.com/sgbalda/verbandsbuch/tree/master/client/src/components): widgets · Reusable forms, admin panels, upload controls, and primitives. · `client/src/components`
- [tRPC client](https://github.com/sgbalda/verbandsbuch/blob/master/client/src/lib/trpc.ts): api client · Typed client used to call backend procedures. · `client/src/lib/trpc.ts`
- [Language/theme](https://github.com/sgbalda/verbandsbuch/tree/master/client/src/contexts): state contexts · Global client-side context for language and theme behavior. · `client/src/contexts`

### Shared domain

Types, constants, and cross-runtime helpers reused by client and server.

- [Domain types](https://github.com/sgbalda/verbandsbuch/blob/master/shared/types.ts): shared types · Common TypeScript domain models and contracts. · `shared/types.ts`
- [Constants](https://github.com/sgbalda/verbandsbuch/blob/master/shared/const.ts): shared constants · Shared enumerations, labels, and domain options. · `shared/const.ts`
- [Shared core](https://github.com/sgbalda/verbandsbuch/tree/master/shared/_core): helpers · Common utility and error helpers used across runtimes. · `shared/_core`

### Server core

Node/Express/tRPC backend, auth, persistence, and side-effect integration.

- [Server entry](https://github.com/sgbalda/verbandsbuch/blob/master/server/_core/index.ts): app bootstrap · Backend wiring and runtime entry points. · `server/_core/index.ts`
- [tRPC router](https://github.com/sgbalda/verbandsbuch/blob/master/server/_core/trpc.ts): api router · Procedure composition and request routing for the API. · `server/_core/trpc.ts`
- [Request context](https://github.com/sgbalda/verbandsbuch/blob/master/server/_core/context.ts): runtime context · Creates per-request state, db access, and user/admin context. · `server/_core/context.ts`
- [Auth layer](https://github.com/sgbalda/verbandsbuch/blob/master/server/_core/auth-router.ts): access control · User authentication and role-based access handling. · `server/_core/auth-router.ts`
- [Admin layer](https://github.com/sgbalda/verbandsbuch/blob/master/server/_core/admin-router.ts): admin access · Admin login, authorization, and privileged operations. · `server/_core/admin-router.ts`
- [SMTP mailer](https://github.com/sgbalda/verbandsbuch/blob/master/server/_core/email-smtp.ts): notification service · Outbound email notifications for assignments and follow-up. · `server/_core/email-smtp.ts`
- [Vite bridge](https://github.com/sgbalda/verbandsbuch/blob/master/server/_core/vite.ts): dev serving · Integration between the backend and Vite during development or serving. · `server/_core/vite.ts`

### Persistence

Database schema, migrations, and runtime file storage.

- [Schema](https://github.com/sgbalda/verbandsbuch/blob/master/drizzle/schema.ts): drizzle schema · Persistent model for plants, areas, reports, roles, audit logs, and actions. · `drizzle/schema.ts`
- [Migrations](https://github.com/sgbalda/verbandsbuch/tree/master/drizzle): drizzle migrations · Versioned SQL changes and schema evolution history. · `drizzle`
- [Relations](https://github.com/sgbalda/verbandsbuch/blob/master/drizzle/relations.ts): db mapping · Table relationship definitions for query-time structure. · `drizzle/relations.ts`
- [Uploads](https://github.com/sgbalda/verbandsbuch/tree/master/uploads): filesystem storage · Local runtime storage for uploaded photos and media. · `uploads`

## Connections

- React app → Pages: renders · Routes and screens are composed into the browser app.
- React app → UI components: uses · Pages are built from reusable UI and workflow components.
- React app → Language/theme: wraps · App shell provides shared client state and localization.
- Pages → tRPC client: calls · User and admin screens invoke backend procedures through typed RPC.
- UI components → tRPC client: submits · Forms and actions send mutations and queries to the server.
- tRPC client → tRPC router: api contract · Frontend and backend share the same typed procedure surface.
- Pages → Domain types: uses · Screens depend on shared domain types and form values.
- UI components → Constants: uses · UI labels, options, and domain constants are shared.
- Server entry → tRPC router: mounts · The backend bootstraps the main API router.
- tRPC router → Request context: builds on · Procedures run with request-scoped context and services.
- tRPC router → Auth layer: protects · User-facing procedures enforce authentication and roles.
- tRPC router → Admin layer: protects · Admin-only procedures apply stricter access control.
- Request context → Schema: queries · Context exposes database access for business operations.
- Request context → Relations: joins · Relational mappings support structured data access.
- tRPC router → SMTP mailer: notifies · Server emits operational emails for assignments and updates.
- Server entry → Vite bridge: integrates · Backend cooperates with Vite for development or serving.
- Request context → Uploads: stores media · Uploaded photos are persisted on the local filesystem.
- Schema → Migrations: evolved by · The schema is applied and changed through migrations.
- Relations → Schema: maps · Relations describe how tables connect in the schema.
- Shared core → Request context: supports · Shared helpers and errors feed backend request handling.
- Shared core → React app: supports · Common utilities can be reused by the browser app.
