Overview

flowgeist.tool — Developer Documentation

flowgeist.tool is a multi-tenant B2B SaaS platform for special-tool management in workshop and branch operations. It covers tool inventory, QR-code-based booking, rentals, damage reports, inspections, reordering, and AI-assisted photo recognition.

Technology Stack

Layer	Technology
Backend	NestJS 11 (Node 22), TypeScript strict
Frontend	Next.js 14 (App Router), next-intl (de/en)
Shared	`packages/shared` — DTOs, enums, error codes
Database	PostgreSQL 16 via Prisma 7 (`@prisma/adapter-pg`)
Cache / Queues	Redis 7 + BullMQ (background jobs, backups, notifications)
Auth	JWT (access + refresh), argon2id password hashing, TOTP MFA
AI	Mistral Vision API (photo recognition, end-of-day check)
Containers	Docker Compose, blue-green production deployment

Repository Layout

flowgeist-tool/
├── apps/
│   ├── api/          # NestJS backend (port 3001)
│   │   ├── prisma/   # Schema, migrations, seed
│   │   └── src/
│   │       ├── common/    # Shared services, guards, filters
│   │       └── modules/   # Feature modules (auth, ai, tools, …)
│   └── web/          # Next.js frontend (port 3000)
├── packages/shared/  # Shared types, error codes, constants
├── docker/           # Compose files, Dockerfiles, ops scripts
├── docs/             # End-user manual (Astro Starlight site)
└── dev-docs/         # This developer documentation (Astro Starlight)

How this site is organized

Getting Started — local setup and the verification pipeline.
Architecture — module system, guard pipeline, multi-tenancy.
Conventions — code style, error codes, secrets handling, git workflow.
Testing — test pyramid and CI pipeline.
Operations — deployment model.
API Reference — generated from the NestJS controllers (always current).

End-user manual: docs.flowgeist-tool.de — German-language user handbook (roles, step-by-step guides).
Repository rules: AGENTS.md in the repo root — the operative rulebook for AI agents and contributors.