How sgbalda/verbandsbuch works
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: trpc.ts tRPC router · context.ts Request context · App.tsx React app · pages Pages
Components 19
Client app
React/Vite browser application and its UI workflow layer.
- React app · Browser-facing application shell and route composition.
client/src/App.tsx - Pages · Home, reporting, updates, and admin screens.
client/src/pages - UI components · Reusable forms, admin panels, upload controls, and primitives.
client/src/components - tRPC client · Typed client used to call backend procedures.
client/src/lib/trpc.ts - Language/theme · 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 · Common TypeScript domain models and contracts.
shared/types.ts - Constants · Shared enumerations, labels, and domain options.
shared/const.ts - Shared core · Common utility and error helpers used across runtimes.
shared/_core
Server core
Node/Express/tRPC backend, auth, persistence, and side-effect integration.
- Server entry · Backend wiring and runtime entry points.
server/_core/index.ts - tRPC router · Procedure composition and request routing for the API.
server/_core/trpc.ts - Request context · Creates per-request state, db access, and user/admin context.
server/_core/context.ts - Auth layer · User authentication and role-based access handling.
server/_core/auth-router.ts - Admin layer · Admin login, authorization, and privileged operations.
server/_core/admin-router.ts - SMTP mailer · Outbound email notifications for assignments and follow-up.
server/_core/email-smtp.ts - Vite bridge · Integration between the backend and Vite during development or serving.
server/_core/vite.ts
Persistence
Database schema, migrations, and runtime file storage.
- Schema · Persistent model for plants, areas, reports, roles, audit logs, and actions.
drizzle/schema.ts - Migrations · Versioned SQL changes and schema evolution history.
drizzle - Relations · Table relationship definitions for query-time structure.
drizzle/relations.ts - Uploads · Local runtime storage for uploaded photos and media.
uploads
Connections 21
- 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.