Repository Map

Basis: Top-level layout and the core/ module list from core/pom.xml; purposes from each folder's README where one exists.
Related: Getting Started · Conventions · System Architecture

1. Top-level folders

Folder	Purpose (source)
`core/`	Java 21 + Spring Boot 3.4 modular monolith; one JAR from `core/app`, plus `app-worker` and `app-jobs` assemblies (README)
`web/`	Next.js tenant console — agents, workflows, knowledge, channels, billing (README)
`web-admin/`	Next.js platform-admin console (`web-admin/README.md`)
`services/sidecar/`	Python + FastAPI knowledge/RAG service: chunking, embeddings, extraction, reranking, transcription
`services/code-intel/`	Multi-tenant code-intelligence service (RAG index, code graph), bridged into core via `core/codeintel`
`services/app-builder/`	No-code app-builder microservice, sibling of code-intel
`services/voice-agent/`	Real-time voice pipeline on LiveKit Agents
`services/tool-sandbox/`	Compiles, verifies and runs tenant-authored Java/Python custom-code tools (ADR-0009)
`services/mcp-stdio-runner/`	Runs STDIO MCP server subprocesses in an isolated container on core's behalf
`services/rl-trainer/`	Offline preference/prompt optimisation sidecar for `core/rl`
`deploy/`	Everything to self-host: `compose/` (Lite, Full, build, `domain`, `ci`, `local-llm` overlays), `helm/` (charts), `kind/`, plus configs for Keycloak, Postgres, Caddy, Prometheus/Grafana/Loki/Promtail, Alertmanager, Temporal, LiveKit, the mock LLM provider and CI seed data. See `deploy/README.md`.
`infra/`	Terraform modules and Keycloak realm material kept from the original hosted deployment. Not used by Compose or Helm and not a supported install path.
`scripts/`	CI gates (`scripts/ci/`), dev tooling (`scripts/dev/`, `dev-up.sh`, `run-core-local.sh`, `vegaduta` CLI helpers), `backup/`, `keycloak/`
`contracts/`	Inbound/outbound wire-format JSON Schemas and fixture corpus
`examples/`	Example MCP servers (`home-assistant`, `http-gateway`) and known-good workflow create-request bodies (`workflow-templates/`)
`tests/`	Standalone Playwright suite for the public surface (`tests/e2e/`) and a k6 load harness (`tests/load/`)
`docs/`	Design notes (`docs/architecture/`), connector specs (`docs/connectors/`), MCP registration guide (`docs/core/`) and this documentation site (`docs/platform-documentation/`)
`.github/`	Workflows, `CODEOWNERS`, PR and issue templates, Dependabot and labeler config
`.githooks/`, `.devcontainer/`	Tracked git hooks (`pre-push`); devcontainer

Also at the root: README.md, CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, LICENSE (Apache-2.0), NOTICE, install.sh, .editorconfig, .gitleaks.toml. No mobile, desktop, IDE or browser-extension clients are part of this repository.

2. `core/` — modules

core/pom.xml (packaging pom, Spring Boot parent 3.4.4, java.version 21) lists the reactor modules, in build order:

audit billing crypto secrets storage speech mcp mcpserver security admin sharing
providers tenancy chat eventbus approval payments knowledge guardrails google sarvam
imagegen elevenlabs sdlc eval graphmemory codeintel documentgen agents quality voice
omnichannel devices workflow platform rl templates brief app-config app app-worker app-jobs

The directories mcp-data and mcp-stdio-proxy also exist under core/ but are not reactor modules. Areas:

Platform/tenancy — tenancy, security, admin, platform, billing
Agent runtime — agents, chat, providers, eval
Automation — workflow, eventbus (Kafka-backed outbox), approval
Knowledge — knowledge, graphmemory (Apache AGE)
Governance — guardrails, audit, mcp (dynamic connector registry)
Channels/devices — omnichannel, devices, sarvam, imagegen, elevenlabs, google
Infra — storage, crypto, secrets, sdlc, codeintel
app — the Spring Boot assembly; this is what runs. app-worker (Temporal worker) and app-jobs (scheduled sweeps) are sibling assemblies from the same codebase; see shape-api/shape-jobs in the Glossary and ADR-0001.
Others: speech, mcpserver, sharing, payments, documentgen, quality, voice, rl, templates, brief, app-config.

Flyway migrations

core/app/src/main/resources/db/migration/ contains controlplane/ and tenant/. Both are one combined version space (README §6) — see Conventions.

3. Two facts that explain most surprises

Schema-per-tenant. Tenant isolation is a Postgres schema resolved from the request's tenant context; hence PgBouncer must stay POOL_MODE=session (README §1).
Flyway versions share one namespace across controlplane/ and tenant/.

Evidence & references

Repository root listing; core/pom.xml — module list and properties.
README.md §1 and §6; READMEs under services/, web-admin/, contracts/, examples/, tests/e2e/, tests/load/.