rentman-clone/.a0/architecture.md

Architecture – Rentman.io Clone

Version: 1.0
Date: 2026-05-31
Project: Rentman.io-Nachbau
Architect: Solution Architect (A0 Software Orchestrator)

---

Table of Contents

1. Tech-Stack
2. System Components
3. API Design
4. Authentication & Authorization
5. Multi-Tenant Strategy
6. Deployment Approach
7. Module Boundaries & Data Flow
8. Risk Notes

---

Tech-Stack

Backend

• Language: Python 3.12+
• Framework: FastAPI 0.115+ (async, high-performance, auto-docs)
• ORM: SQLAlchemy 2.0 with Alembic for migrations
• Database: SQLite for local development → PostgreSQL 16 for production
• Caching: Redis for session storage, rate limiting, and cache layer
• Background Tasks: Celery with Redis broker for async jobs (PDF generation, email)
• File Storage: Local filesystem for dev; S3-compatible (MinIO/AWS S3) for production

Frontend

• Language: TypeScript 5.x (strict mode)
• Framework: React 19 with React Router 7 (routing), TanStack Router also considered
• State Management: Zustand (global), React Query (server state)
• UI Library: Tailwind CSS 4 + Radix UI (accessible headless components)
• Build Tool: Vite 6
• Testing: Vitest + React Testing Library
• Mobile (PWA): Service Worker with Workbox, Capacitor (for native camera/barcode)

Mobile App (PWA)

• Progressive Web App with offline support (Service Workers)
• Barcode scanning via Capacitor's Barcode Scanner plugin
• IndexedDB for local data store; sync with backend via REST API

DevOps & Deployment

• Containerization: Docker & Docker Compose
• CI/CD: GitHub Actions (build, test, lint, migrate, deploy)
• Environment: Local dev with Docker Compose; production on Coolify (CapRover alternative)
• Monitoring: Prometheus + Grafana (optional), Sentry for error tracking

---

System Components

┌─────────────────────────────────────────────────────────────────────────────┐
│                          Rentman-Clone System                               │
│                                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │  React SPA   │  │  PWA Mobile  │  │ External APIs│  │  Admin CLI   │    │
│  │  (Browser)   │  │  (Capacitor) │  │  (Webhooks)  │  │  (optional)  │    │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘    │
│         │                │                 │                 │              │
│         └────────────────┴────────┬────────┴─────────────────┘              │
│                                   │                                         │
│                          ┌────────▼────────┐                                │
│                          │   Nginx Reverse  │                                │
│                          │   Proxy (TLS)    │                                │
│                          └────────┬────────┘                                │
│                                   │                                         │
│                          ┌────────▼────────┐                                │
│                          │   FastAPI App     │                               │
│                          │   (Backend API)   │                               │
│                          │   Port 8000       │                               │
│                          └───┬───────┬───────┘                               │
│                              │       │                                       │
│                 ┌────────────▼──┐ ┌──▼────────────┐                         │
│                 │  Celery Worker │ │   PostgreSQL  │                          │
│                 │ (Background)   │ │  / SQLite     │                          │
│                 │  + Redis Queue │ │               │                          │
│                 └───────┬────────┘ └───────────────┘                          │
│                         │                                                    │
│              ┌──────────▼──────────┐                                        │
│              │   Object Storage     │                                        │
│              │  (MinIO / S3)        │                                        │
│              └─────────────────────┘                                        │
└─────────────────────────────────────────────────────────────────────────────┘

Component Descriptions

• React SPA: Client-side rendered app, communicates via JSON REST API, handles UI rendering. Built with Vite for fast builds.
• PWA Mobile App: Same React codebase but served with Service Worker for offline capability; uses Capacitor for camera/barcode scanning. Can be deployed as TWA (Trusted Web Activity) on Android or via iOS WebAPKs.
• External APIs (Webhooks): Endpoints for third-party integrations (calendars, external CRM/ERP). Can also consume webhooks.
• Nginx Reverse Proxy: SSL termination, static file serving (for SPA), rate limiting, and optional load balancing.
• FastAPI Backend: RESTful API with JWT auth, RBAC, openapi schema. Implements all business logic. Uses SQLAlchemy async sessions.
• Celery Worker: Offloads long-running tasks: PDF generation, mass exports, email sending, webhook dispatching. Uses Redis as message broker.
• Redis: Used for Celery broker, also for caching query results (Redis Cache), session storage, and rate limiting counters.
• PostgreSQL / SQLite: SQLite for local dev (single file), PostgreSQL for production. Both accessed through same SQLAlchemy models, migrations applied via Alembic.
• Object Storage (MinIO/S3): Stores uploaded documents, equipment images, generated PDFs/CSVs. Provides signed URLs for download.

---

API Design

General Principles

• RESTful JSON API.
• Base URL: /api/v1/ (versioned for future updates).
• Authentication: Bearer JWT token in Authorization header.
• Standard HTTP status codes: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable, 500 Internal Server Error.
• Pagination: all list endpoints return JSON with items, total, page, size.
• Filtering: query parameters ?status=X&project_type=Y&sort=created_at&order=asc.
• Nested resources for sub-entities (e.g., /projects/{project_id}/subprojects).
• OpenAPI (Swagger) auto-generated at /docs and /redoc.

Endpoint Overview

Auth:

• POST /api/v1/auth/login – login (email, password) → JWT token + refresh token
• POST /api/v1/auth/refresh – refresh token
• POST /api/v1/auth/register – self-service registration (tenant creation)

Users & Roles:

• GET/POST /api/v1/users – list/create users (admin)
• GET/PUT/DELETE /api/v1/users/{id} – user CRUD
• GET/PUT /api/v1/roles – roles management

Projects:

• GET/POST /api/v1/projects – list/create
• GET/PUT/DELETE /api/v1/projects/{id} – project CRUD
• GET /api/v1/projects/{id}/subprojects – subprojects
• POST /api/v1/projects/{id}/subprojects – create subproject
• GET/PUT/DELETE /api/v1/projects/{project_id}/subprojects/{id} – subproject CRUD
• Project function groups: /projects/{project_id}/functiongroups (nested)
• Project functions: /projects/{project_id}/functiongroups/{group_id}/functions
• Equipment groups: /projects/{project_id}/equipmentgroups
• Equipment items within group: /projects/{project_id}/equipmentgroups/{group_id}/equipment
• Crew assignments: /projects/{project_id}/crew (via functions)
• Vehicle assignments: /projects/{project_id}/vehicles
• Quotes: /projects/{project_id}/quotes
• Invoices: /projects/{project_id}/invoices

Equipment Catalog:

• GET/POST /api/v1/equipment – list/create
• GET/PUT/DELETE /api/v1/equipment/{id} – CRUD
• GET /api/v1/equipment/{id}/availability – availability timeline

Crew Catalog:

• GET/POST /api/v1/crew – list/create
• GET/PUT/DELETE /api/v1/crew/{id} – CRUD
• GET /api/v1/crew/{id}/availability – availability

Vehicles:

• GET/POST /api/v1/vehicles – list/create
• GET/PUT/DELETE /api/v1/vehicles/{id} – CRUD

Contacts:

• GET/POST /api/v1/contacts – list/create
• GET/PUT/DELETE /api/v1/contacts/{id} – CRUD

Project Requests:

• GET/POST /api/v1/requests – public/private
• GET/PUT /api/v1/requests/{id} – read/update
• POST /api/v1/requests/{id}/convert – convert to project

Documents:

• GET/POST /api/v1/documents – list/upload
• GET/DELETE /api/v1/documents/{id} – download/delete
• Templates: /api/v1/templates (admin)

Reports:

• GET /api/v1/reports/finance – financial KPIs
• GET /api/v1/reports/equipment-utilization – equipment utilization
• GET /api/v1/reports/project-stats – project statistics

Export:

• POST /api/v1/export/{module} – asynchronous export to CSV/Excel

Webhooks:

• GET/POST /api/v1/webhooks – manage webhook subscriptions
• POST /api/v1/webhooks/{id}/trigger – test trigger

Admin:

• GET /api/v1/audit-log – audit log entries

---

Authentication & Authorization

Authentication

• JWT access tokens (short-lived, 30 minutes) + refresh tokens (24 hours, stored in httpOnly cookie or secure storage).
• Password hashing with bcrypt.
• Optional OAuth2/OpenID Connect in V2 (not MVP).
• Self-service registration creates a new tenant account (company) and admin user.

Authorization – RBAC

• Role-based access control with four fixed roles: Admin, Project Manager, Warehouse Operator, Freelancer.
• Custom roles can be defined later; permissions are defined as granular rights:
  • Module-level: projects:read, projects:write, projects:delete, equipment:read, etc.
  • Object-level: user can only access projects they are assigned to (or all for admin).
• Roles are stored as list of permissions in Role model.
• Middleware checks token claims and resolves permissions; Depends() function in FastAPI routes.

Multi-Tenant Strategy

• Shared Database with Tenant ID: Each table contains a tenant_id (UUID) foreign key to Account table.
• Row-Level Security: SQLAlchemy queries automatically filter by the tenant associated with the authenticated user's account_id (from JWT).
• Isolation: one account cannot see another's data.
• Onboarding: registration creates a new Account and an initial admin user.

---

Deployment Approach

Local Development

• Docker Compose with services: backend (FastAPI hot-reload), frontend (Vite dev server), PostgreSQL, Redis, MinIO.
• SQLite as default for quick dev (just set DATABASE_URL=sqlite:///./rentman.db), but Docker-Compose uses PostgreSQL.
• No volumes; data in container.

Production (Coolify)

• Docker Compose as deployable artifact.
• Coolify handles SSL, domain routing, environment variables.
• CI/CD: GitHub Actions build test, then push image to registry; Coolify webhook triggers redeploy.
• Database backups via Coolify's built-in PostgreSQL backup feature.
• File storage: S3 bucket (MinIO or AWS S3).

Scalability

• Backend stateless → horizontal scaling with multiple API instances behind load balancer.
• Celery workers can be scaled independently.
• PostgreSQL read replicas for heavy reporting.

---

Module Boundaries & Data Flow

React SPA <──> FastAPI <──> SQLAlchemy <──> Database
                       <──> Celery (Redis) <──> Email/PDF/S3

Modules (in backend):

• auth – login, register, refresh
• users – user management, roles
• projects – project CRUD, subprojects, function groups, functions
• equipment – equipment catalog, categories, stock locations
• crew – crew catalog, availability
• vehicles – vehicles, assignments
• contacts – contacts (companies/persons)
• project_requests – public request handling
• quotes_invoices – quotes, invoices, templates, PDF generation
• documents – file uploads, downloads
• reports – analytics endpoints
• webhooks – manage subscriptions, dispatch

Frontend (React):

• pages/ – top-level routes
• components/ – reusable UI (forms, tables, modals)
• hooks/ – custom hooks for API calls
• stores/ – Zustand stores (global state)
• services/ – API client (axios/fetch wrappers)
• i18n/ – translations (DE, EN)

---

Risk Notes

• SQLite vs PostgreSQL discrepancies: SQLite doesn't support some SQL features (e.g., ALTER COLUMN). Use Alembic to handle dialect differences; tests must run on PostgreSQL.
• Offline Sync Conflicts: Offline-first with Last-Write-Wins may cause data loss if two users edit same entity offline. For MVP, limited to equipment status and packlist checkmarks; acceptable.
• Performance with large rental sets: 500k equipment items → need indexing on tenant_id, status, and category. Reporting queries may be slow; consider materialized views.
• Security: JWT secret must be managed; never hardcoded. Use environment variable. Rate limiting prevents brute-force attacks.
• Multi-Tenant Data Isolation: Must ensure all queries include tenant filter. Implement a SQLAlchemy query filter on session creation to avoid accidental leaks.
• PWA Barcode Scanning: Capacitor camera plugin may require additional permissions; need to handle permission prompts gracefully.
• Complexity of Project Hierarchy: Project → Subproject → FunctionGroup → Function → (Crew/Equipment) is deep; ensure API design is consistent and documentation clear.