Tech Stack

Lumie is intentionally split across a local-first web frontend, a single Spring Boot modular monolith, a small set of independent FastAPI workers, and a GitOps-managed platform layer. This page summarizes the main technology choices and how they fit together.

Stack at a Glance

Area	Primary choices	Notes
Frontend	Next.js 16 App Router, React 19, TypeScript 5	The browser app runs locally in dev and uses same-origin /api/... proxy routes to reach the backend.
Frontend state and forms	TanStack Query, Zustand, React Hook Form, Zod	Query state, local UI state, and typed form validation are handled separately instead of through one global store.
Frontend styling and UI	Tailwind CSS 4, Radix UI, class-variance-authority, lucide-react	Shared UI primitives live alongside product-specific widgets and feature slices.
Frontend API contract	OpenAPI via springdoc, orval code generation	The backend publishes /v3/api-docs, and the frontend generates entity-scoped React Query clients from the committed snapshot.
Backend runtime	Java 21, Spring Boot 3.4, Spring Security, Spring Data JPA, Bean Validation	Core product logic lives in one deployable application with code-level module boundaries.
Backend modularity and jobs	Spring Modulith, JDBC event publication, ShedLock, Bucket4j	Modulith events back cross-module async work, ShedLock protects scheduled jobs, and Bucket4j handles per-pod rate limiting.
Workers	Python 3.11+, FastAPI, Pydantic v2, aio-pika, httpx	Workers stay separate only where a different runtime or scaling model is useful.
Data and messaging	PostgreSQL, RabbitMQ, Redis, MinIO	PostgreSQL is the source of truth, RabbitMQ carries background jobs, Redis supports cache-like workloads, and MinIO stores objects.
Platform	K3s, ArgoCD, Traefik, Vault Secrets Operator, Cert-Manager, Zot	The cluster is GitOps-managed, secrets come from Vault, and images are mirrored through Zot.
Observability and security	Prometheus, Grafana, Loki, Tempo, OpenTelemetry, Kyverno, Falco	Platform visibility and policy are handled outside product repos in lumie-infra.
Developer tooling	Tilt, Gradle, Testcontainers, ArchUnit, Vitest, Playwright, Ruff, mypy, Docusaurus 3	Tooling follows repo boundaries instead of forcing one stack across every repo.

Source Anchors

Path	What it anchors
lumie-frontend/package.json	Next.js, React, TypeScript, TanStack Query, Zustand, React Hook Form, Zod, Tailwind, Radix UI, Orval, Vitest, and Playwright dependencies
lumie-frontend/app/api/[...path]/route.ts	The frontend's same-origin API proxy contract
lumie-backend/gradle/libs.versions.toml	Java, Spring Boot, Spring Modulith, ShedLock, Bucket4j, springdoc, MinIO, and ArchUnit versions
lumie-backend/app/build.gradle.kts	The backend runtime and test stack actually assembled into the deployable
lumie-worker/pyproject.toml	Workspace-wide Python 3.11, Ruff, and mypy baseline
lumie-worker/services/{analysis,grading,report,chatbot}/pyproject.toml	Per-service FastAPI, aio-pika, httpx, and observability dependencies
lumie-infra/bootstrap/kustomization.yaml	Bootstrap-owned platform services such as MinIO, Zot, and Vault
lumie-infra/platform/kustomization.yaml	Traefik, cert-manager, RabbitMQ, KEDA, and other cluster-wide platform services
lumie-infra/{bootstrap,platform,storage,security,observability,applications}/application.yaml	Argo CD-managed GitOps slice layout
lumie-document/docusaurus/package.json	Docusaurus 3 site tooling

Frontend

The frontend lives in lumie-frontend and is built on Next.js App Router with React 19 and TypeScript. Its codebase uses a Feature-Sliced-style structure under src/shared, src/entities, src/features, and src/widgets, and the import direction is enforced in ESLint rather than left as a convention.

Data fetching is generated from the backend OpenAPI spec through orval, with TanStack Query used as the client runtime. Forms use React Hook Form plus Zod, local UI state uses Zustand where needed, and the visual layer is built with Tailwind CSS 4 and Radix-based primitives.

Backend

The backend lives in lumie-backend and is a modular monolith, not a microservice fleet. app produces one Spring Boot deployable, while modules/* and libs/* define the internal module boundaries. The runtime stack centers on Spring Web, Spring Data JPA, Spring Security, and Bean Validation.

Spring Modulith is used for durable after-commit event publication, springdoc-openapi exposes the HTTP contract, ShedLock protects scheduled jobs in multi-pod deployments, and Bucket4j provides token-bucket rate limiting. The backend build uses Gradle with Java 21 toolchains, Spotless, Error Prone, JaCoCo, ArchUnit, and Testcontainers-backed integration tests.

Workers

The worker repo, lumie-worker, contains several separately deployed FastAPI services such as grading, report generation, analysis, and chatbot workloads. These services share a Python 3.11 baseline plus FastAPI, Pydantic v2, and process environment-based configuration.

RabbitMQ consumers use aio-pika, backend calls use httpx, and object-backed workflows use MinIO. The repo standardizes on Ruff for formatting and linting and mypy for type checking.

Data and Messaging

PostgreSQL is the main transactional store. Lumie uses a shared public schema with tenant-scoped tables protected by Row Level Security, so multi-tenancy is enforced in the database rather than by a schema-per-tenant design.

RabbitMQ handles asynchronous workflows such as grading and report generation. Redis is present for platform-backed cache or coordination needs, and MinIO stores uploaded files and generated artifacts.

Platform and Delivery

lumie-infra manages the platform as a GitOps repo. The cluster runs on K3s, ArgoCD reconciles application state, Traefik handles ingress, Cert-Manager issues certificates, and Vault plus Vault Secrets Operator supply runtime secrets. Images are expected to flow through Zot instead of being pulled directly from public registries.

For day-to-day development, Tilt ties the local and cluster pieces together: the frontend runs on the developer machine with HMR, while the backend, workers, and stateful services run in the dev cluster.

Contract and Documentation Tooling

Two supporting tools are part of the day-to-day stack:

• Docusaurus 3 powers the product documentation site in lumie-document.
• .codex holds the shared workflow, routing, rules, and automation conventions for work across repos.

Verification

Use the checked-in manifests and package files as the source of truth for stack claims:

cd /Users/bluemayne/Projects/Lumie
rg -n "\"next\"|\"react\"|\"typescript\"|\"@tanstack/react-query\"|\"zustand\"|\"react-hook-form\"|\"zod\"|\"tailwindcss\"|\"orval\"|\"vitest\"|\"@playwright/test\"" \
  lumie-frontend/package.json
rg -n "java +=|spring-boot +=|spring-modulith +=|shedlock +=|bucket4j +=|springdoc-openapi +=|archunit +=|testcontainers|spring-boot-starter-security|spring-boot-starter-data-jpa" \
  lumie-backend/gradle/libs.versions.toml \
  lumie-backend/app/build.gradle.kts
rg -n "requires-python|fastapi==|aio-pika==|httpx==|prometheus-client==|opentelemetry-" \
  lumie-worker/pyproject.toml \
  lumie-worker/services/analysis/pyproject.toml \
  lumie-worker/services/grading/pyproject.toml \
  lumie-worker/services/report/pyproject.toml \
  lumie-worker/services/chatbot/pyproject.toml
rg -n "minio/argocd.yaml|zot/argocd.yaml|vault/argocd.yaml|traefik-config/argocd.yaml|cert-manager/argocd.yaml|rabbitmq/argocd.yaml|keda/argocd.yaml" \
  lumie-infra/bootstrap/kustomization.yaml \
  lumie-infra/platform/kustomization.yaml
rg -n "\"@docusaurus/core\"|\"@docusaurus/preset-classic\"" \
  lumie-document/docusaurus/package.json

Success signals:

• Frontend dependency manifests still show the framework, state, form, styling, and testing libraries listed in this page.
• Backend version catalogs and app build files still show one Java 21 and Spring Boot 3.4-based deployable with Modulith, ShedLock, Bucket4j, springdoc, ArchUnit, and Testcontainers.
• Worker service manifests still declare Python 3.11 FastAPI runtimes, with aio-pika only on queue-driven services and httpx on services that call back into the platform.
• Infrastructure kustomizations still place Vault, Zot, Traefik, cert-manager, RabbitMQ, and KEDA in the platform layer described here.

Where To Go Next

• Architecture Overview for the runtime shape across all repos.
• Workspace for the multi-repo layout.
• Tilt for the local frontend and cluster-backed dev loop.
• Backend Modules for monolith boundaries.
• Multi Tenancy for the PostgreSQL RLS model.
• Documentation for Docusaurus authoring rules.
• Agent Engineering for Lumie's workflow control plane.