Workspace

Lumie is a multi-repo workspace. The root folder is not one application repository with subfolders; it is a coordination layer that holds several independent Gitea repos side by side. Day-to-day work usually touches one or two repos at a time, but the workspace is designed so shared rules, routing, and local development still feel consistent.

Main Repositories

Path	Role
lumie-frontend	Next.js web application for staff, students, onboarding, and marketing surfaces
lumie-backend	Spring Boot modular monolith for product business logic
lumie-worker	Independent FastAPI workers for grading, reports, analysis, and chatbot workloads
lumie-infra	GitOps-managed K3s platform, application manifests, storage, security, and observability
lumie-document	Docusaurus documentation site
lumie-graph	Graphify output and AST-based cross-repo lookup support
.codex	Shared workflow control plane: agents, routing, knowledge, rules, lint, and hooks
.github	Shared scripts and CI helpers, including the workspace Tilt entrypoint

How The Workspace Is Meant To Be Used

The repos are intentionally separate because they have different runtimes, deployment boundaries, and review rules. The frontend is a local Node.js app, the backend is a Java monolith, the workers are Python services, the platform is Kubernetes and GitOps config, and the docs site is its own static build. Keeping them split makes those boundaries explicit.

At the same time, root-level guidance keeps the developer experience unified:

• Root AGENTS.md defines the shared working rules.
• .codex provides workflow routing, review expectations, specialist agents, guardrails, and knowledge that apply across repos.
• .github/tilt-up.sh starts the normal local development loop from the workspace root.

Local Versus Cluster Responsibilities

The normal dev loop is intentionally hybrid:

• The frontend runs locally on the developer machine at http://localhost:3000.
• The backend, workers, PostgreSQL, RabbitMQ, Redis, and MinIO run in the dev cluster.
• The frontend talks to the backend through its own same-origin proxy routes, so browser auth and local cookies still work cleanly.

This split keeps frontend HMR fast without asking the cluster to run next dev, while still letting backend and worker code run close to the shared stateful services.

The Role Of .codex

.codex is the workspace control plane, not product code. It holds:

• agents/ for specialist definitions
• routing/ for repo cards, loop contracts, verification selectors, review routing, and commit policy
• knowledge/ for cross-repo rules, architecture intent, and glossary material
• rules/ and lint/ for path-scoped policy, pattern sweeps, and validation
• hooks/ and hooks.json for workspace guardrails

If you are returning to an unfamiliar area, start with the root rules and then the repo you plan to edit rather than treating every sub-repo as independent from scratch.

A Good First Orientation Pass

1. Read the root AGENTS.md.
2. Read the affected repo's AGENTS.md.
3. Check .codex/routing/repos/<repo>.md when the repo has route-specific instructions.
4. Follow the local dev path in Tilt if you need a running environment.
5. Use Agent Engineering when the task depends on Lumie's entry gate, execution loops, routing, or reviewer conventions.

Where To Go Next

• Tilt for the normal local development loop.
• Documentation for Docusaurus authoring rules in lumie-document.
• Agent Engineering for workflow and routing conventions.
• Architecture Overview for the cross-repo runtime picture.