System Context (C4 L1) -- TalkIDE Internal Docs

TalkIDE internal documentation

The TalkIDE platform, the people who use it, and the external systems it depends on.

flowchart TB
    subgraph actors[" "]
        direction LR
        EU["End User<br/>(Vibecoder)"]
        OP["Platform Operator<br/>(TalkIDE staff)"]
        AEU["App End User<br/>(audience of a published app)"]
    end

    TID["<b>TalkIDE Platform</b><br/>Build, run & publish web apps<br/>by talking to Mara"]

    subgraph ext["External systems"]
        direction LR
        ANT["Anthropic API<br/>Claude — every Mara turn"]
        STRIPE["Stripe<br/>Payments & invoices (test mode)"]
        MG["Mailgun<br/>Transactional email"]
        DO["DigitalOcean<br/>K8s · Managed PG ×2 · Spaces<br/>Registry · LB · DNS"]
        GL["GitLab<br/>Source repos & CI"]
        PB["Porkbun<br/>Domain registrar (talkide.app)"]
    end

    EU -->|"workspace + Studio<br/>talkide.app"| TID
    OP -->|"admin console (planned)"| TID
    AEU -->|"{slug}.talkide.app"| TID

    TID -->|"agent turns (via gateway-proxy)"| ANT
    TID -->|"SetupIntent · invoices · webhooks"| STRIPE
    TID -->|"password reset · waitlist · invites"| MG
    TID -->|"compute · data · blobs · DNS"| DO
    TID -->|"build & deploy TalkIDE itself"| GL
    PB -.->|"delegates DNS to DO"| DO

Actors

Actor	Description	Primary entry point
End User (Vibecoder)	Non-technical individual or small business owner who builds their own app by talking to Mara. Owns one tenant.	`https://talkide.app` (workspace + Studio)
Platform Operator	TalkIDE staff. Manages capacity, invite cascade, fatigue overrides, emergency brake, issue triage, waitlist invites. (Admin Console — UC-08004 — planned.)	`https://talkide.app/admin` (planned)
App End User (audience of a published user app)	Anyone visiting a user-published app (e.g. customers of `wildwood-bakery.talkide.app`). Has no TalkIDE account.	`https://<slug>.talkide.app`

External systems

System	Used for	TalkIDE’s dependency
Anthropic API	Every Mara / subagent turn	Hard dependency. The platform gateway-proxy holds the raw `ANTHROPIC_API_KEY`; the agent runtime never sees it directly (see ADR-024). CLI mode in local dev uses Max-plan auth on the host.
Stripe	Payment method on file, invoices, AI credit top-up, postpaid hosting charges, webhooks	Hard for billing. Test mode in production today — live-mode flip is a separate runbook. No Subscriptions; Customer + SetupIntent/PaymentIntent + invoices only. See UC-10.
Mailgun	Transactional email — password reset, waitlist confirmation, invite emails	Hard for those flows. Sending subdomain `mail.talkide.app` (does not touch apex MX). Dev/test profiles send to `/dev/null`. See ADR-025.
DigitalOcean Kubernetes (`talkide-prod`, NYC3)	Compute for TalkIDE platform pods, per-tenant worker pods, ephemeral build/test Jobs, and all user-app pods	Hard. Node pool `s-4vcpu-8gb`. Per-tenant-environment namespaces provisioned on demand. See ADR-015.
DigitalOcean Managed Postgres (two clusters)	Cluster A `talkide-prod-pg` — control-plane DB (platform + session state). Cluster B `talkide-dataplane-pg` — data-plane, schema-per-app for user apps.	Hard. Two physically separate PG 18 clusters. See ADR-023 and `infrastructure.md`.
DigitalOcean Spaces (`talkide-prod-space`)	User-app uploads, generated content (PDFs, exports), platform backups/exports/logs/artifacts	Hard for any user app that does file I/O. S3-compatible API, prefix isolation per app.
DigitalOcean DNS (`talkide.app`)	Apex + `api.` + wildcard `*.talkide.app` for user apps	Hard. Authoritative on `ns{1,2,3}.digitalocean.com`.
DigitalOcean Container Registry (`registry.digitalocean.com/talkide`)	Built images for TalkIDE BE/FE, `talkide-worker`, the shared userapp build cache, and every published user app	Hard. Professional plan — unlimited repos.
GitLab (`talkide` group)	Source repositories (`talkide-be`, `talkide-fe`, `documentation`, `talkide-infra`, `talkide-worker`, blog, docs) and manual-gated CI for the platform itself	Hard for platform delivery. Not used for user-app source — those keep local `.git/` only (ADR-013).
Porkbun	Domain registrar for `talkide.app`	Soft — registration only; DNS itself is delegated to DigitalOcean.
Self-hosted NFS (in-cluster)	Per-project working tree (source + local `.git/` history) shared between BE, worker pods and build Jobs	Hard. Backed by DO Block Volume `talkide-prod-nfs-vol`. Managed NFS not yet available in NYC3.
End user’s browser	Renders TalkIDE workspace, Studio, Project Explorer, and user-generated apps	Modern evergreen browsers; SSE via fetch parser (ADR-008).

What TalkIDE is not responsible for

Custom domains for published user apps. User apps are reachable only under <slug>.talkide.app in MVP. Bring-your-own-domain is post-alpha.
External Git remotes. TalkIDE-managed user projects keep local .git/ history but no push to GitHub/GitLab. A curated export feature is planned post-alpha.
Real-money payments today. Stripe runs in test mode; live-mode flip is a deliberate operational step (UC-10 runbook).
Live human technician support. Planned monetization feature; no model or UI yet.

Trust boundaries

Browser
  │  TLS
  ▼
talkide.app (TalkIDE workspace, Studio, auth) — operated by TalkIDE
  │  REST + SSE (Bearer JWT)
  ▼
api.talkide.app  →  TalkIDE BE pod  (control-plane, ns talkide)
  │  ├─ gateway-proxy ──► Anthropic API   (BE holds the raw API key)
  │  ├─ Stripe / Mailgun  (HTTPS, secrets in K8s)
  │  ├─ control-plane PG (cluster A, via PgBouncer)
  │  └─ K8s API ──► provisions per-tenant-environment namespaces
  ▼
tenant-environment namespace (e.g. mirek-prod)
  │  talkide-worker pod  ── agent runtime, SSE, dispatches build/test Jobs
  │  (worker calls gateway-proxy; never holds the Anthropic key)
  ▼
data-plane PG (cluster B, schema-per-app, self-host PgBouncer SCRAM)

Browser
  │  TLS
  ▼
<uuid>.talkide.app   — per-project DEV preview (Mara-built code)
<slug>.talkide.app   — per-project PROD published (user-promoted code)
  │  user-defined REST → user-app BE pod → user-app schema (cluster B)
  ▼
DO Spaces (per-app prefix) for blobs

The trust boundary that matters most: anything written into CLAUDE.md is shared with Anthropic as part of the LLM context. Only data with explicit user consent (salutation, team briefing) crosses it. See mara-context.md § Privacy principle.

Was this page helpful?

Thanks for the feedback.