Architecture

How the repo's pieces — core, modules, agent-runtime, backend — fit together.

Repo map

Path	What lives there
core/	Flutter shell — tab registry, identity switcher, design system, platform-service seams, CoreContext
modules/	Feature modules (vitals, sample); each is module.yaml + schema/ + agent/ + lib/ (surface)
app/	Thin Flutter entrypoint that composes core + the enabled module tabs
agent-runtime/	Python agent framework (config/pb/llm/run; jarvis_platform seams)
core/agent/	The core brief agent (Python)
backend/	Baked PocketBase migrations + generated manifest
cli/	The jarvis CLI (module new, module add, deploy)
tools/checks/	Contract + CI parity guards
docs/	Specs, plans, and the authoring guide

This table is reproduced from the root README. Two other top-level directories exist alongside these but aren't part of that table: docker/ (the compose bootstrap/scheduler build context) and dev-vault/ (the scheduler's writable vault volume, seeded with example notes for dev).

The dependency direction only ever points from app/ down into core/ and modules/*, never the other way — that's what lets a module be added, removed, or broken without the core knowing or caring. See Authoring a module for the module-side contract this enables, and Dev setup & the gate for the full-repo gate every package and Python suite must pass.

Codegen and generated artifacts

Enabling a module (jarvis module add <name>) never hand-wires anything — it appends the module to the root modules.yaml, then regenerate() (cli/src/jarvis_cli/codegen.py) rewrites the same four generated artifacts from scratch, from the full set of enabled modules' manifests:

• app/lib/generated/enabled_modules.dart — imports every enabled module's surface package and concatenates their tab lists, in modules.yaml order. Carries a // GENERATED … DO NOT EDIT header.
• backend/generated/manifest.json — one entry per enabled module: its migrations directory, its agent path (or null), and its contributes / schedules / secrets blocks when present.
• backend/generated/crontab — the scheduler's supercronic-format crontab, one block per module with a schedules: entry.
• The managed block in app/pubspec.yaml, fenced by # jarvis:modules:begin … # jarvis:modules:end markers — a local path dependency on each surfaced module's package.

None of these four are hand-edited; they're build output, rewritten wholesale on every module add.

jarvis deploy (cli/src/jarvis_cli/deploy.py) reads backend/generated/manifest.json and stages the baked migration set: core migrations from backend/pb_migrations/ first, then every enabled module's migrations, copied into backend/generated/module_pb_migrations/ and namespaced mod_<module>_<orig> — e.g. modules/sample/schema/pb_migrations/1_init_sample.js becomes mod_sample_1_init_sample.js. The namespacing keeps filenames unique across modules and sorts them after the timestamp-prefixed core migrations. deploy executes no Docker itself — it's a P0 skeleton that echoes the multi-arch build/push commands and the scheduler crontab that would ship.

The agent framework split

The Python side of agent-runtime/src/ is split into two packages:

Package	Modules	Role
jarvis_agent	config, pb, llm, audit, redact, run	The module-agnostic shell: config loading, the PocketBase client, the LLM call, audit logging, redaction, and run_proposal() — the trigger → gather context → LLM → validate → write → HUMAN APPROVE GATE pipeline every module agent runs on.
jarvis_platform	rag, knowledge, recurrence, handle_match	Cross-module platform seams — retrieval-augmented generation, the knowledge/semantic-index layer, recurrence handling, and entity/handle matching.

jarvis_agent owns the pipeline mechanics (idempotency, one repair round on a validation failure, dry-run, rollback of an orphaned primary record); it never auto-approves — the approve/edit gate is downstream, in the client. A module supplies a ProposalSpec on top of this shell rather than reimplementing the pipeline; see Authoring a module for where a module's agent/agent.py plugs in.

For where jarvis_platform's RAG and knowledge seams surface to an end user, see Using It → Chat & RAG and Using It → Semantic index. For the CLI that drives scaffolding and deploy, see Operating → The jarvis CLI.