Architecture

Spark is a set of small services written in TypeScript and run with Bun. The browser talks to one public backend; everything else is internal.

Services

Service	Responsibility
spark_marketing_frontend	The web app (Next.js, React). Client pages such as /launch and /strategy, and the staff area under /system.
spark_marketing_backend	The front door. Sign-in, organizations, users, roles and permissions, plans, campaigns and leads, AI model choice. Proxies /launch/* and /system/launch/* to spark_launch after checking permissions.
spark_marketing_socket	Realtime gateway (Socket.IO). Consumes events and pushes them to connected browsers.
spark_meta	Facebook and Instagram integrations: account connection, webhooks, messaging, publishing, insights. Exposes read-only snapshots for launch checks.
spark_tiktok_snapchat	TikTok (organic and ads) and Snapchat integrations. Exposes read-only snapshots for launch checks.
spark_whatsapp	WhatsApp messaging.
spark_mail	Sends email from clients' verified domains and addresses. Internal only.
spark_flows	Visual automation flows for campaigns, ad groups and ads.
spark_launch	Launch readiness, business identity, brand kit, verification documents, launch content translation, notifications and the strategy workspace. Internal only.
spark_storage	A library, not a service: one storage facade with interchangeable drivers and a single key grammar.
spark_contracts	A library: shared TypeScript types, the event topic catalogue and envelope, hashing helpers. See Shared contracts.

How they talk

Browser ──HTTPS──▶ frontend ──▶ backend (public API)
                                   │  checks session + permission
                                   │  signs a service token
                                   ▼
                 spark_launch, spark_flows, spark_mail, ... (internal HTTP)
                                   │
          spark_launch ──service token──▶ spark_meta / spark_tiktok_snapchat / backend
                                         (read-only snapshot routes)

Services ◀──── event bus (Kafka, topics and envelope from spark-contracts) ────▶ socket gateway

• Synchronous calls are HTTP with a short-lived signed service token. See Service-to-service auth.
• Asynchronous work goes over Kafka, using the topic names and message envelope defined in spark-contracts.
• Each service owns its own MongoDB database. Services never read another service's database; they ask the owning service.

Inside spark_launch

Module	Owns
catalogue	Versioned data: stages, criteria, guides, glossary, size table, sources.
checks	The check runner, platform snapshot client and the nightly job.
launches	Launches, cells, the event log, the evaluator and readiness.
identity	Business identity, brand kit, encrypted documents, the access log, retention.
i18n	Content per language, review state, machine translation.
notify	The daily digest of new "needs you" and "needs a fix" items.
strategy	Strategy versions, provenance, approval, suggestions, the monitor and the monthly review.
health	GET /health.

AI text (descriptions, translations, strategy drafts) is requested from the backend, which owns model choice. Answers are validated against a schema before they are stored; a failed answer never blocks the client.