Single source of truth for TalkIDE-specific terminology. When a new term is introduced in any overview file, it must be defined here first.
Personas
| Term | Definition |
|---|---|
| Mara | The AI Product Manager in TalkIDE. Talks to the user, plans the work, delegates to subagents. Implemented as a Claude-powered agent persona; runs via MaraExecutor (CLI or Agent SDK sidecar). |
| Kai | Mara’s devops subagent — handles cloud deploys (ADR-012). One of the team members Mara delegates to. |
| Mara’s team | The set of subagents Mara orchestrates: backend developer, frontend developer, devops (Kai), tester, analyst. Defined as plugin agent files (agents/talkide-*.md). |
| Vibecoder | The non-technical end user building their own app on TalkIDE. |
| Platform Operator | TalkIDE staff. Manages capacity, fatigue overrides, invites. Future Admin Console — UC-08004. |
| Founder | The seed identity at the root of the invite cascade (ADR-020). |
Product concepts
| Term | Definition |
|---|---|
| Vibecoding | Describing what you want in natural language and getting a working web app. |
| Vibemanagement | Same idea, applied to changes: describe a change, a new ProjectVersion is created, applying it deploys it live. |
| Project | The user’s web app being built. One row in PROJECT. Carries a slug, accent, tech stack, status. |
| App (generated user app) | The runtime artifact deployed from a Project — a Spring Boot BE pod + Vue/Vite FE pod + per-app DB in their own namespace. Reachable at <uuid>.talkide.app (DEV) and/or <slug>.talkide.app (PROD). |
| Tenant | Top-level scope in TalkIDE platform DB. Owns Projects. One per user in MVP. |
| Conversation | Multi-turn chat with Mara, scoped to a Project. One ACTIVE per Project. |
| ProjectVersion | Snapshot of a Project. Created when the user asks Mara to “apply”. Linear versionNumber. Status DRAFT/APPLYING/APPLIED/ROLLED_BACK/FAILED. |
| Activity | One discrete event emitted during a Mara turn — TASK_STARTED, TOOL_USE, AGENT_MESSAGE, TASK_COMPLETED. Categorised by ToolCategory. Source for both UC-05 and UC-06 feeds. |
| ToolCategory | Business-level enum over Claude tool names: READING / EDITING / EXECUTING / DELEGATING / BROWSING / OTHER. Drives consecutive-coalesce dedup (ADR-009). |
| Studio | Tenant-level command center — cross-project recent activity feed (UC-06). |
| Project Explorer | The “under-the-hood” mode (UC-07): files tree + DB explorer, read-only. |
Lifecycle / runtime
| Term | Definition |
|---|---|
| DEV preview | Per-project preview environment at <uuid>.talkide.app. Re-builds on every Mara change. Throwaway DB. |
| PROD published | Per-project stable environment at <slug>.talkide.app. Only redeploys on explicit user Publish. Persistent DB. |
| Stopa B | Internal name for the build/deploy pipeline track: B.0.1 snapshot → B.0.2 build → B.4 deploy → B.5 ingress → B.6 health → B.7 publish. ADR-018/019/017/021. |
| Stopa C | Internal name for the platform-DB observability/governance track. (Not yet documented in detail.) |
| Stopa D | Internal name for the GDPR / data-export track. (Mentioned in CLAUDE.md DO Spaces platform/exports/.) |
| Apply (a version) | User action that promotes a ProjectVersion to APPLIED — triggers build + deploy of DEV preview. |
| Publish | User action that promotes the current preview to a PROD <slug>.talkide.app deployment. |
| DRAFT → PUBLISHED state machine | The two-environment lifecycle behind the Publish button. |
AI / quota
| Term | Definition |
|---|---|
| MaraExecutor | Pluggable interface for running a Mara turn. Implementations: ClaudeCliExecutor (Max plan, local dev) and NetworkWorkerExecutorConfig (HMAC worker-token, talkide-worker pod — LIVE since 2026-05-21). AgentSidecarExecutor (in-process sidecar) has been replaced per ADR-024. |
| Sidecar | The former in-process Node.js runtime of @anthropic-ai/claude-agent-sdk co-resident with the TalkIDE BE pod. Replaced by talkide-worker on 2026-05-21 per ADR-024. |
| talkide-worker | LIVE since 2026-05-21 (ADR-024 krok 6). A thin Node/TS worker pod, one per tenant-environment namespace, running the Anthropic Agent SDK in-process. NetworkWorkerExecutorConfig active, HMAC worker-token provider active. Stateful (session, transcript on NFS, 3-week resume), survives BE redeploys. Calls the gateway-proxy — never holds the raw Anthropic key. Remaining backlog: gradle build/test Jobs (be#213/218 — planned), gateway-proxy as standalone component (be#214 — planned). |
| gateway-proxy | The part of TalkIDE BE that holds the raw ANTHROPIC_API_KEY and proxies all agent inference calls. Centralises rate-limiting, billing accounting and secret custody so the worker pod only ever holds an internal HMAC token (ADR-024 §3). |
| Anthropic Call Gateway | UC-08001 — central wrapper around MaraExecutor that records every turn into api_usage_ledger. |
| FUP | Fair Use Policy — per-user spend cap enforced by rolling Redis windows (5h + weekly). UC-08002 (planned). |
| Fatigue states | UX rendering of FUP state — Mara’s avatar degrades as the user approaches the cap (FRESH → TIRED → EXHAUSTED → ASLEEP). |
| Grace finish | Once a turn starts, it finishes even if mid-turn the user crosses the FUP cap. Quota is checked before each turn, never mid-turn. |
| Model swap | Under fatigue, Mara may run on a cheaper model to extend headroom. |
| Founder-gated invite cascade | TalkIDE alpha is closed-pool; a tree of invite tokens rooted at the founder identity. (UC-08003, planned.) |
| Global emergency brake | Platform-wide kill-switch independent of per-user FUP. (UC-08004, planned.) |
Infrastructure
| Term | Definition |
|---|---|
| NFS | Self-hosted ReadWriteMany volume backed by DO Block Volume talkide-prod-nfs-vol. Holds per-project working trees + local .git/ history + build pipeline workspace. Pods mounting it run as non-root UID 1000+ (root squashing). |
| Spaces | DO’s S3-compatible blob store. Single bucket talkide-prod-space with prefix isolation per app and platform/ prefixes for backups/exports/logs/artifacts. |
| Control-plane DB / cluster A | talkide-prod-pg — DO Managed PG 18 cluster holding the platform DB talkide and durable session state. Fronted by PgBouncer pools talkide-tx (transaction, size 18) and talkide (session, size 3). See ADR-023. |
| Data-plane DB / cluster B | talkide-dataplane-pg — a physically separate DO Managed PG 18 cluster holding talkide_dataplane, one schema per user app. Fronted by a self-hosted PgBouncer with SCRAM-SHA-256. |
| schema-per-app | The data-plane isolation model: each user app gets a schema tk_t<tenantId>_p<slug>_<env> + a per-app role + ALTER ROLE … SET search_path. Supersedes the old DB-per-app model (ADR-016). |
| PgBouncer pooling | Connection pooler in front of both PG clusters. Cluster A uses DO Managed PgBouncer (talkide-tx / talkide pools); cluster B uses a self-hosted PgBouncer because only it supports client→pooler SCRAM-SHA-256 with auth_query. |
| dataplane | Shorthand for the data-plane: cluster B + its self-hosted PgBouncer + the per-app schemas. The control-plane is the BE + cluster A. |
| tenant zero | The TalkIDE platform itself, modelled as the first tenant inside the data-plane scheme (ADR-023) — it eats its own dog food. |
| Per-app DB | (Legacy term, ADR-016.) The old model gave each user app its own logical database. Superseded by schema-per-app on cluster B. |
| Tenant namespace / tenant-environment namespace | K8s namespace per tenant-environment (e.g. mirek-prod, popelkam-talkide). The substrate for data-plane isolation, the home of the talkide-worker pod and of build/test Jobs. (ADR-015, ADR-023 §5, ADR-024). |
| Environment | A first-class domain concept (ADR-026) — a named runtime context (kind DEFAULT / USER_CREATED, resource_mode SHARED / DEDICATED) sitting alongside Project and Domain. Formalises the two implicit DEV/PROD environments into an explicit entity with its own namespace, data-plane scope and billing rows. |
.talkide/ | Per-project directory inside the working tree. Holds the rsync-copy of the Mara plugin, project.yml, and a placeholder team/ for future per-project agent overrides. (ADR-011) |
.talkide/project.yml | Structured per-project config. The deterministic source of port numbers (BE = 8090 + id, FE = 5200 + id) and URLs. Plugin scripts read it via yq, never from text. |
| CLAUDE.md (per-project) | Human briefing for Mara at the root of a project. BE re-renders it before every spawn. Only consent-bound user data may go inside (see mara-context.md § Privacy principle). |
| Plugin | The shared TalkIDE-team Claude Code plugin (talkide-be/plugin/). Rsync-copied per project on every spawn so per-project tweaks are possible. |
External integrations
| Term | Definition |
|---|---|
| Stripe | Payment provider (UC-10). One Stripe Customer per user, lazy-created. Used for a payment method on file + invoice generation + AI credit top-up + postpaid hosting charges — no Subscriptions. Test mode in production today; live-mode flip is a separate runbook. |
| Mailgun | Transactional email provider (ADR-025). Sends password-reset, waitlist-confirmation and invite emails from subdomain mail.talkide.app. Dev/test profiles send to /dev/null. |
| Postpaid hosting | Hosting/infra billing model (ADR-026): metered accrual into hosting_cost_events, billed as one monthly Stripe invoice per tenant with per-environment line items. AI stays prepaid (credit top-up). |
Reserved namespaces
| Term | Definition |
|---|---|
| Reserved slug | A subdomain prefix the user cannot pick for their app slug. List lives in CLAUDE.md root → Reserved slugs. Enforced at Create Project. |
| Apex | talkide.app — TalkIDE workspace. Distinct from api.talkide.app (BE) and *.talkide.app (user apps). |
Was this page helpful?
Thanks for the feedback.