§ 04 · Architectural decisions
How Khala is wired — and why.
The interesting choices, not the obvious ones. Every decision below has a trade-off
the project accepted on purpose.
flowchart TB
user([you / client])
ui["Angular UI"]
gw["Unified API\nFastAPI gateway\n(optional security pre-scan)"]
subgraph teams ["mounted teams · /api/[slug]"]
direction LR
core["🛠 Core dev"]
biz["💼 Biz"]
content["✍ Content"]
personal["🧘 Personal"]
more["…"]
end
subgraph runtime ["execution runtime"]
direction LR
threads["threads\n(default)"]
temporal["Temporal workflows\n(opt-in · TEMPORAL_ADDRESS)"]
end
shared[("shared · Postgres · AGENT_CACHE · LLM client")]
user --> ui --> gw
gw --> core
gw --> biz
gw --> content
gw --> personal
gw --> more
teams --> threads
teams --> temporal
threads --> shared
temporal --> shared
classDef gw fill:#140a2e,stroke:#5ef0ff,stroke-width:1.5px,color:#ece7ff
classDef team fill:#0d0622,stroke:#8b5cff,stroke-width:1px,color:#ece7ff
classDef rt fill:#0d0622,stroke:#ffd36b,stroke-width:1px,color:#ece7ff
classDef shared fill:#140a2e,stroke:#ff5cd4,stroke-width:1.5px,color:#ece7ff
class gw gw
class core,biz,content,personal,more team
class threads,temporal rt
class shared shared
SE team pipeline — one spec in, a deployable system out.
flowchart LR
spec["initial_spec.md"]
subgraph d1 ["1 · Discovery"]
parse["LLM spec parse"]
plan["Planning v2/v3\n(6-phase)"]
parse --> plan
end
subgraph d2 ["2 · Design"]
tl["Tech Lead"]
arch["Architecture Expert"]
master["master_plan.md"]
tl --> master
arch --> master
end
subgraph d3 ["3 · Execution"]
direction TB
prefix["Prefix queue\ngit + DevOps"]
be["Backend worker\ngenerate → lint → build → review → QA"]
fe["Frontend worker\ngenerate → lint → build → review → QA"]
prefix --> be
prefix --> fe
end
subgraph d4 ["4 · Integration"]
integ["Integration Agent\n(contract check)"]
devops["DevOps trigger"]
sec["Final security pass"]
docs["Docs update"]
integ --> devops --> sec --> docs
end
spec --> d1 --> d2 --> d3 --> d4
classDef phase fill:#0d0622,stroke:#8b5cff,stroke-width:1px,color:#ece7ff
classDef node fill:#140a2e,stroke:#5ef0ff,stroke-width:1px,color:#ece7ff
class d1,d2,d3,d4 phase
class spec,parse,plan,tl,arch,master,prefix,be,fe,integ,devops,sec,docs node
ADR-01
One unified gateway, not a service mesh
Every team mounts under /api/<slug> behind a single FastAPI app. The
security pre-scan lives at the gateway (SECURITY_GATEWAY_ENABLED=true) so
it's applied once, consistently, and teams don't each re-roll their own auth layer.
Trade-off we took: every team shares a process in local dev. Good for velocity, bad for strict blast-radius isolation — Docker mode gives each team its own container for that.
ADR-02
Durability is opt-in, not mandatory
If TEMPORAL_ADDRESS is set, teams that export WORKFLOWS /
ACTIVITIES from <team>/temporal/__init__.py switch from threads
to Temporal 1.24.2 workflows — progress survives server restarts. If it's not set,
everything still runs as background threads.
Trade-off we took: two execution paths to maintain. In exchange, local dev stays zero-dependency and production gets crash-resumable pipelines.
ADR-03
Shared Postgres schema registry
Teams export a SCHEMA: TeamSchema constant (pure data, no side effects); each
team's lifespan calls register_team_schemas(SCHEMA) at startup. No
POSTGRES_HOST? Registration no-ops. Teams get transactional storage without
a per-team migration runner.
Trade-off we took: no SQLite fallback for migrated teams — they require Postgres. Docker compose brings one up; local dev needs the env vars. We picked consistency over "runs anywhere."
ADR-04
Team-lead orchestrator + Pydantic contracts
Every team has a team-lead agent that coordinates specialists through typed request/response
models. You get runtime validation, free OpenAPI docs, and a contract the agents can't
silently break.
Trade-off we took: contracts are heavier to evolve than loose dict-passing. We picked the compile-time safety net over the freeform flexibility.
ADR-05
Pluggable LLM client
A single llm_service wraps Ollama (local or Cloud) and Claude behind one API,
with generate_structured doing Pydantic validation + one schema-grounded
self-correction retry. Per-role overrides (e.g. ARCHITECT_MODEL_SPECIALIST,
BLOG_PLANNING_MODEL) let specific agents pick their own model without
forking a client.
Trade-off we took: model-specific features lose fidelity behind the abstraction. We keep the escape hatch open: teams that need a raw provider call still have it.
ADR-06
Declarative agent manifests
The Agent Console reads per-agent YAML manifests from
backend/agents/<team>/agent_console/manifests/*.yaml. Each describes id,
team, summary, I/O schema refs, invoke metadata, and sandbox provisioning hints — and they
drive the UI catalog plus the /api/agents endpoint automatically.
Trade-off we took: every new specialist gets a YAML companion. We took the authoring cost to remove the "how do I even discover this agent?" problem.
ADR-07
Warm per-team sandboxes for isolated invocation
The Agent Console Runner invokes a single specialist in a warm Docker sandbox per team
(sandbox.compose.yml, dedicated sandbox-postgres, isolated network,
ports 8200–8220). Sandboxes are reused across invocations and reaped after
SANDBOX_IDLE_TEARDOWN_MINUTES (default 15).
Trade-off we took: cold-start latency on first invocation per team. In exchange, agents tagged requires-live-integration stay catalogued but clearly marked unrunnable — no silent breakage.
ADR-08
Named volume, team-namespaced paths
Every containerized team mounts the same agents_data named volume at
/data/agents and sets AGENT_CACHE=/data/agents. Teams
self-namespace under {team_name}/. Job state, caches, profiles, workspaces —
all persist across restarts without per-team volume plumbing.
Trade-off we took: teams share a filesystem root. We trust namespacing over isolation at this layer; the stronger isolation story lives at the Temporal/Postgres layer.
