Skip to content
flowgeist.tool — Developer Docs

System Overview

System Overview

Section titled “System Overview”

flowgeist.tool is a pnpm monorepo with three deployable parts plus a shared package:

┌─────────────┐     HTTPS      ┌──────────────────────────────────┐
│  Next.js 14 │ ─────────────► │           NestJS 11 API          │
│  (apps/web) │   /api/...     │           (apps/api)             │
└─────────────┘                │                                  │
                               │  Guard pipeline → Modules        │
                               │  Prisma 7 ──► PostgreSQL 16      │
                               │  BullMQ   ──► Redis 7            │
                               │  Mistral Vision API (external)   │
                               └──────────────────────────────────┘
                                        ▲
                               ┌────────┴─────────┐
                               │  Worker (BullMQ) │  backups, sync jobs,
                               │  (Docker)        │  notifications
                               └──────────────────┘

Applications

Section titled “Applications”

apps/api — NestJS backend

Section titled “apps/api — NestJS backend”
  • Feature modules under src/modules/ (auth, tenancy, tools, rentals, damages, ai, notifications, webhooks, provisioning, …).
  • Cross-cutting services under src/common/ (SecretService, guards, exception filter, tenant resolver).
  • Database access exclusively via Prisma 7 with @prisma/adapter-pg (driver adapter on pg). The datasource URL lives in apps/api/prisma.config.ts (Prisma 7 style — not in the schema).
  • All routes are served under the global prefix api (app.setGlobalPrefix('api')), e.g. GET /api/v1/tools.

apps/web — Next.js frontend

Section titled “apps/web — Next.js frontend”
  • App Router with route groups per functional area.
  • Internationalization via next-intl (German default, English).
  • Role-aware UI: the permission model is mirrored in the frontend; navigation and actions follow the user’s role/permissions.
  • PWA assets (manifest, icons, service worker) for workshop tablet use.

Worker (BullMQ)

Section titled “Worker (BullMQ)”
  • Same codebase/image family as the API, running queue consumers: daily encrypted database backups, notification dispatch, synchronization jobs.

packages/shared

Section titled “packages/shared”
  • Shared DTOs, enums, constants and the TT-xxx error code catalog.
  • Imported by both apps/api and apps/web — a single source of truth for contracts between frontend and backend.

Data stores

Section titled “Data stores”
Store Usage
PostgreSQL 16 All business data; multi-tenant schema (see Multi-Tenancy)
Redis 7 BullMQ queues, caching, rate limiting

External services

Section titled “External services”
Service Purpose
Mistral AI Vision models for tool photo recognition and the end-of-day check
SMTP / Web Push Notifications (email + VAPID web push)

Request lifecycle (API)

Section titled “Request lifecycle (API)”
Request
  → ThrottlerGuard        (rate limiting)
  → TenantResolverGuard   (resolve tenant from host/path/claim)
  → JwtAuthGuard          (verify access token; skipped for @Public())
  → RoleGuard             (role check via @Roles())
  → ModuleGuard           (permission check via @Permissions())
  → Controller → Service → Prisma → PostgreSQL

Errors are normalized by a global exception filter into TT-xxx codes — see Error Codes.