System Requirements Document for emergent-bolt

1. Introduction

emergent-bolt is an AI application-generation platform that clones the Emergent platform's processes, workflows, architecture, internal processes, agents, swarms, sandbox, environment, high-quality output, token handling, and repositories, and adds additional functions and features drawn from Bolt and Lovable. The product intent is to let a Builder describe an application in natural language and have a coordinated system of agents and swarms plan, generate, and run that application inside a sandboxed environment, producing high-quality output, a repository, and visible token consumption — while a Platform Operator configures the agents and swarms and oversees sandbox provisioning, token consumption, and repositories so builds complete reliably.

The audience is two-fold: Builders (technical founders, indie hackers, product engineers) who expect a generation run to feel like commanding a machine, and Platform Operators who watch agents, swarms, sandboxes, and token burn as live telemetry. The product lives in a dark control room: an idea becomes a running app with visible machinery.

This document is the System Requirements Document for emergent-bolt, written for the requester Guneet Bajaj.

2. System Overview

emergent-bolt is delivered as a first-party web application with application-owned identity and durable state. It comprises:

• A React frontend presenting the public Landing, identity surfaces (Sign Up, Login), Builder workspaces (Dashboard, New Build, Build Details, Sandbox, Token Usage, Repositories), and Operator workspaces (Agents & Swarms, Operations).
• A shared FastAPI backend hosting all application APIs and domain modules: identity, builds, agent/swarm orchestration, sandbox and environment provisioning, token accounting, and repository management.
• MariaDB for application-owned persistent data (accounts, builds, agent/swarm configuration, sandbox records, token records, repository records).
• Redis for shared caching, run-state coordination, and background job/queue coordination for generation runs.
• LiteLLM as the model-provider gateway used by the backend for all agent and swarm model calls, backed by its own PostgreSQL instance (separate from application-owned storage).

Actors are the Builder and the Platform Operator. Builders self-enroll, describe apps, run and iterate on builds, inspect agent/swarm activity, run sandboxes, view token usage, and access repositories. Platform Operators are provisioned or invited, then configure agents and swarms and oversee sandbox/environment provisioning, token consumption, and repositories.

Background automation is part of the accepted delivery shape: generation runs execute asynchronously (planning → agent/swarm execution → sandbox provisioning → repository creation), with live status surfaced to the Builder and telemetry surfaced to the Operator.

Removed from scope

• None.

2a. Product Interpretation and Delivery Boundary

emergent-bolt is a first-party, application-owned product. Identity is application-owned: Builders self-enroll through Sign Up and verify on return through Login; Platform Operators are provisioned or invited and then verify through Login. Protected Builder and Operator destinations require an authenticated session; the Landing, Sign Up, and Login are anonymously reachable.

Generation runs are executed by the platform's own backend and background workers, calling model providers only through the LiteLLM gateway. Sandboxes and environments are provisioned and owned by the platform. Repositories produced for builds are managed and surfaced by the platform. Token consumption is metered by the platform against the gateway.

Everything described in this document is current scope. No future-horizon capabilities are declared by the source.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous public entry. Explains the app-building platform, agent/swarm generation, sandboxed environments, and repositories before sign-in. Presents the hero (see §7) and a HUD strip with live-style mono readouts (AGENTS · SWARM · SANDBOX · TOKENS).
• Primary actions: Enter Sign Up (primary CTA); enter Login.
• Supporting actions: Navigate to sections describing agents/swarms, sandbox, and repositories.
• Domain entities: None persisted; presentation of platform concepts only.
• Component responsibilities: Hero WebGL swarm scene; HUD header band (11px uppercase mono micro-label above 1px cyan rule); primary CTA; HUD telemetry strip.
• States: Loading (hero scene initializing — static node graph shown until ready); empty n/a; success (scene live); error (WebGL unavailable → static node graph fallback); recovery (reduced-motion → static arrangement).

Sign Up

• Information/state: Anonymous self-service enrollment for Builders. Collects the information needed to establish a Builder account.
• Primary actions: Submit enrollment to create a Builder account.
• Supporting actions: Navigate to Login.
• Domain entities: Builder account.
• Component responsibilities: Enrollment form; validation; submit control; link to Login.
• States: Loading (submitting); empty (blank form); success (account created → proceed to Login or authenticated entry); error (validation failure, duplicate account); recovery (correct and resubmit).

Login

• Information/state: Anonymous returning verification for Builders and Platform Operators.
• Primary actions: Submit credentials to establish an authenticated session.
• Supporting actions: Navigate to Sign Up (Builders).
• Domain entities: Account, session.
• Component responsibilities: Credential form; validation; submit control; error display.
• States: Loading (verifying); empty; success (session established → route by role to Dashboard or Operations); error (invalid credentials); recovery (retry).

Dashboard

• Information/state: Authenticated Builder entry hub. Summarizes the Builder's projects and routes to builds, sandbox, tokens, and repositories. HUD header band; token bezel gauge echoed in bottom HUD strip.
• Primary actions: Start a New Build; open a Build Details.
• Supporting actions: Navigate to Sandbox, Token Usage, Repositories.
• Domain entities: Project, Build, Sandbox, Token record, Repository.
• Component responsibilities: Project summary list; navigation rail; token gauge; HUD strip.
• States: Loading (fetching projects); empty (no builds yet → prompt to start a New Build); success (projects listed); error (fetch failure → retry); recovery.

New Build

• Information/state: Authenticated Builder. Focused owner for submitting a natural-language app description that starts planning and generation.
• Primary actions: Submit the app description to start a generation run.
• Supporting actions: Review the submitted description before submission.
• Domain entities: Build, generation run.
• Component responsibilities: Prompt input; submit control; run-start confirmation; routing to Build Details on start.
• States: Loading (submitting/starting run); empty (no description); success (run started → Build Details); error (submission failure → retry); recovery.

Build Details

• Information/state: Authenticated Builder. Revisitable owner for reviewing agent and swarm workflow activity, generated output, and iterating on the application. Live node graph of agent/swarm activity; run timeline; generated output preview.
• Primary actions: Iterate on the application (submit a refinement); open the Sandbox; open the Repository.
• Supporting actions: Review agent log stream; review token consumption for the build.
• Domain entities: Build, generation run, agent activity, swarm activity, generated output, token record, repository.
• Component responsibilities: Live node graph (pulsing cyan edges, magenta critical-event flares; readable as timeline in reduced-motion); agent log stream; run timeline; output preview; iteration input; token gauge.
• States: Loading (run in progress); empty (no activity yet); success (output available); error (run failure → surface failure and allow retry/iteration); recovery.

Sandbox

• Information/state: Authenticated Builder. Owner for running the generated application in a sandboxed environment with its own environment configuration. Preview sits inside a luminous wireframe volume frame with corner brackets and mono status readout.
• Primary actions: Run/start the sandbox; interact with the running application.
• Supporting actions: View environment configuration; view sandbox status.
• Domain entities: Sandbox, environment configuration, running application.
• Component responsibilities: Wireframe preview frame; status readout; environment configuration panel; run control.
• States: Loading (provisioning); empty (not yet provisioned); success (running); error (provisioning/run failure → retry); recovery.

Token Usage

• Information/state: Authenticated Builder. Owner for viewing token usage associated with the Builder's builds. Circular bezel gauge with monospace tabular numerals.
• Primary actions: Review token usage per build.
• Supporting actions: Navigate to a Build Details.
• Domain entities: Token record, Build.
• Component responsibilities: Bezel gauge; per-build usage list; tabular numerals.
• States: Loading; empty (no usage yet); success (usage listed); error (fetch failure → retry); recovery.

Repositories

• Information/state: Authenticated Builder. Owner for accessing repositories produced for the Builder's projects.
• Primary actions: Open a repository produced for a project.
• Supporting actions: Navigate to the associated Build Details.
• Domain entities: Repository, Project, Build.
• Component responsibilities: Repository list; open control; linkage to build.
• States: Loading; empty (no repositories yet); success (repositories listed); error (fetch failure → retry); recovery.

Agents & Swarms

• Information/state: Authenticated Platform Operator. Operator-owned configuration of agents and swarms matching Emergent's internal processes. Live swarm canvas; agent log stream; telemetry strip.
• Primary actions: Configure agents; configure swarms.
• Supporting actions: Review live swarm activity and agent logs.
• Domain entities: Agent, Swarm, agent/swarm configuration.
• Component responsibilities: Swarm canvas (node graph); agent log stream; configuration controls; telemetry strip.
• States: Loading; empty (no agents/swarms configured); success (configuration saved and live); error (save failure → retry); recovery.

Operations

• Information/state: Authenticated Platform Operator. Operator-owned oversight of sandbox and environment provisioning, token consumption, and repositories for reliable builds. Dense three-band composition: live swarm canvas top, agent log stream centre, telemetry strip bottom.
• Primary actions: Oversee sandbox/environment provisioning; monitor token consumption; manage repositories.
• Supporting actions: Review agent log stream and telemetry.
• Domain entities: Sandbox, environment, token record, repository, build.
• Component responsibilities: Live swarm canvas; agent log stream; telemetry strip; provisioning/token/repository oversight panels.
• States: Loading; empty (no active operations); success (telemetry live); error (fetch failure → retry); recovery.

3. Functional Requirements

FR-1 — Clone Emergent's platform capabilities (explicit) As a Builder, I should use a platform that matches Emergent's processes, workflows, architecture, internal processes, agents, swarms, sandbox, environment, high-quality output, token handling, and repositories, so that the platform delivers the same class of app-generation experience.

• Trigger/input: Builder uses the platform.
• Observable result: The platform exhibits Emergent-matching processes, workflows, architecture, internal processes, agents, swarms, sandbox, environment, high-quality output, token handling, and repositories.
• Access: Authenticated Builder for protected work; anonymous for public entry.
• Failure/recovery: Surface failures and allow retry.
• Continuation: Return to Dashboard / Build Details.

FR-2 — Add Bolt and Lovable features (explicit) As a Builder, I should have additional functions and features drawn from Bolt and Lovable available on the platform, so that the platform extends beyond Emergent's baseline.

• Trigger/input: Builder uses the platform.
• Observable result: Additional functions and features from Bolt and Lovable are present.
• Access: Authenticated Builder.
• Failure/recovery: Surface failures and allow retry.
• Continuation: Continue in the relevant workspace.

FR-3 — Self-service Builder enrollment (required_inference) As a prospective Builder, I should enroll myself through Sign Up so that I can create builds.

• Trigger/input: Anonymous visitor submits enrollment on Sign Up.
• Observable result: Builder account created; Builder can verify via Login.
• Access: Anonymous.
• Failure/recovery: Validation/duplicate errors surfaced; correct and resubmit.
• Continuation: Proceed to Login.

FR-4 — Returning verification (required_inference) As a Builder or Platform Operator, I should verify on return through Login so that I can access my protected builds, sandboxes, tokens, repositories, and operational state.

• Trigger/input: Submit credentials on Login.
• Observable result: Authenticated session established; routed to Dashboard (Builder) or Operations (Operator).
• Access: Anonymous entry; protected destinations thereafter.
• Failure/recovery: Invalid credentials surfaced; retry.
• Continuation: Enter the appropriate workspace.

FR-5 — Operator provisioning/invitation (required_inference) As a Platform Operator, I should be provisioned or invited before accessing agents, swarms, and operations oversight, so that operator capabilities remain controlled.

• Trigger/input: Provisioning/invitation establishes the Operator account.
• Observable result: Operator can verify via Login and reach Agents & Swarms and Operations.
• Access: Provisioned/invited; authenticated thereafter.
• Failure/recovery: Unprovisioned access denied; contact provisioning owner.
• Continuation: Login.

FR-6 — Submit a natural-language app description (explicit, via New Build) As a Builder, I should describe an app in natural language on New Build and submit it so that the platform plans and generates the application.

• Trigger/input: Description submitted on New Build.
• Observable result: Generation run started; routed to Build Details.
• Access: Authenticated Builder.
• Failure/recovery: Submission failure surfaced; retry.
• Continuation: Build Details.

FR-7 — Review agent and swarm workflow activity (explicit) As a Builder, I should review agent and swarm workflow activity on Build Details so that I can see how the application is being generated.

• Trigger/input: Open Build Details.
• Observable result: Live node graph and agent log stream displayed.
• Access: Authenticated Builder.
• Failure/recovery: Fetch failure surfaced; retry.
• Continuation: Iterate or open Sandbox/Repository.

FR-8 — Iterate on the generated application (explicit) As a Builder, I should iterate on the generated application from Build Details so that I reach a working, deployable product.

• Trigger/input: Submit a refinement on Build Details.
• Observable result: New generation activity; updated output.
• Access: Authenticated Builder.
• Failure/recovery: Run failure surfaced; retry/iterate.
• Continuation: Review output; open Sandbox.

FR-9 — Run the application in a sandboxed environment (explicit) As a Builder, I should run the generated application in a sandboxed environment with its own environment configuration on Sandbox so that I can see it running.

• Trigger/input: Start sandbox on Sandbox.
• Observable result: Application running in sandbox; status readout.
• Access: Authenticated Builder.
• Failure/recovery: Provisioning/run failure surfaced; retry.
• Continuation: Interact with running app.

FR-10 — View token usage (explicit) As a Builder, I should view token usage associated with my builds on Token Usage so that I understand consumption.

• Trigger/input: Open Token Usage.
• Observable result: Per-build token usage displayed.
• Access: Authenticated Builder.
• Failure/recovery: Fetch failure surfaced; retry.
• Continuation: Open Build Details.

FR-11 — Access repositories (explicit) As a Builder, I should access repositories produced for my projects on Repositories so that I can use the generated code.

• Trigger/input: Open Repositories.
• Observable result: Repositories listed and openable.
• Access: Authenticated Builder.
• Failure/recovery: Fetch failure surfaced; retry.
• Continuation: Open Build Details.

FR-12 — Configure agents and swarms (explicit) As a Platform Operator, I should configure agents and swarms on Agents & Swarms so that the platform's internal processes match Emergent's.

• Trigger/input: Edit and save configuration.
• Observable result: Configuration saved; live swarm canvas reflects it.
• Access: Authenticated Platform Operator.
• Failure/recovery: Save failure surfaced; retry.
• Continuation: Review live activity.

FR-13 — Oversee sandbox/environment provisioning, token consumption, and repositories (explicit) As a Platform Operator, I should oversee sandbox and environment provisioning, token consumption, and repositories on Operations so that builds complete reliably and output quality stays high.

• Trigger/input: Open Operations.
• Observable result: Telemetry and oversight panels displayed.
• Access: Authenticated Platform Operator.
• Failure/recovery: Fetch failure surfaced; retry.
• Continuation: Act on oversight findings.

4. User Personas

Builder

• Product context: A technical founder, indie hacker, or product engineer who describes an app idea in natural language and expects the platform to plan, generate, and run it in a sandboxed environment with high-quality output.
• Primary goal: Reach a working, deployable product.
• Distinct responsibilities: Enroll via Sign Up; verify via Login; submit descriptions on New Build; review agent/swarm activity and iterate on Build Details; run the app on Sandbox; review token usage on Token Usage; access repositories on Repositories.
• Inputs/decisions: The app description; refinement decisions; when to run the sandbox; which repository to open.
• Interactions: With the platform's agents and swarms (via Build Details); with the Platform Operator indirectly through the platform's provisioning and oversight.
• Observable success: A running application in the sandbox, a produced repository, and visible token usage.

Platform Operator

• Product context: Responsible for the platform's internal processes: configuring agents and swarms, overseeing sandbox and environment provisioning, monitoring token consumption, and managing repositories so that builds complete reliably and output quality stays high.
• Primary goal: Keep builds reliable and output quality high.
• Distinct responsibilities: Provisioned/invited access; verify via Login; configure agents and swarms on Agents & Swarms; oversee provisioning, token consumption, and repositories on Operations.
• Inputs/decisions: Agent/swarm configuration decisions; oversight actions on provisioning, tokens, and repositories.
• Interactions: With Builders indirectly through the platform's builds and telemetry.
• Observable success: Reliable builds, controlled token consumption, and healthy repositories visible in Operations.

5. Core User Flows

Flow A — Builder enrollment and first build

1. Anonymous visitor lands on Landing; reads the platform explanation and HUD strip.
2. Selects the primary CTA → Sign Up.
3. Submits enrollment; account created.
4. Proceeds to Login; verifies; session established.
5. Routed to Dashboard; selects New Build.
6. On New Build, submits a natural-language app description.
7. Generation run starts; routed to Build Details.
8. Reviews live node graph and agent log stream; output appears.
9. Iterates with a refinement; updated output.
10. Opens Sandbox; starts the sandbox; app runs in wireframe frame.
11. Opens Repositories; opens the produced repository.
12. Opens Token Usage; reviews consumption.

• Failure/recovery: Submission or run failure surfaced on the relevant page with retry.

Flow B — Builder returning session

1. Returns to Login; verifies.
2. Routed to Dashboard; opens an existing Build Details.
3. Continues iteration, sandbox, repositories, or token review.

Flow C — Platform Operator configuration and oversight

1. Operator is provisioned/invited.
2. Verifies via Login; routed to Operations.
3. Opens Agents & Swarms; configures agents and swarms; saves.
4. Reviews live swarm canvas and agent log stream.
5. Returns to Operations; oversees sandbox/environment provisioning, token consumption, and repositories.

• Failure/recovery: Save or fetch failure surfaced with retry.

6. Visuals Colors and Theme

Muse: Gleb Kuznetsov — cinematic future tech; the swarm as a living instrument panel.

Palette (dark mode):

• Background: #07090F (~70% of every screen)
• Surface: #0E1320 at 60–80% opacity, 1px rgba(57,230,255,0.22) borders
• Text: #E8EEF9 (15:1 on ground)
• Primary: #39E6FF (working signal — active agents, running sandboxes, primary CTAs)
• Accent: #FF3DBE (scarce ~5% — swarm-critical events, token-burn spikes, live badges)
• Muted: #7C8AA5 (micro-labels, secondary data)

Typography:

• Headings: Space Grotesk, 500–700, tight -0.02em tracking at display sizes
• Body: Space Grotesk
• Data: JetBrains Mono, 13px tabular
• Micro-labels: 11px uppercase, 0.18em letterspacing
• Scale (1.4 modular): display clamp(48px, 7vw, 112px) / h1 clamp(36px, 4.5vw, 64px) / h2 clamp(26px, 3vw, 40px) / h3 22px / body 16px / micro-label 11px / data 13px. Mobile floor 48px display, 36px h1; nothing below 11px.

Shape language: Full-bleed dark canvas; thin luminous 1px strokes; 2px cyan inner-glow edges; floating glass panels 16px radius with 1px light borders; radial/orbital layouts for agent graphs; hairline horizontal rules; sharp-cornered inset HUD readouts; circular progress rings and bezel gauges.

Layout: Fixed left rail (72px icon-only at 768px, 240px at 1280px); 12-column grid; operator views dense three-band; builder pages one dominant subject per viewport; full-width dark bands separated by 1px cyan rules.

Imagery: Abstract 3D and procedural only — glowing volumetric core, orbiting agent nodes, particle token flow, luminous wireframe sandbox volumes, HUD overlays. No stock photography, no people, no clip art, no gradient blobs.

Accessibility: Readable text and controls stay whole at 375px, 768px, 1280px; never cropped or covered. Never place cyan text below 16px on panels without a darker backing.

7. Signature Design Concept

The public entry is a full-bleed #07090F void with a single crafted WebGL scene: a volumetric cyan swarm core off-centre right at 55% viewport width, agent nodes orbiting on thin luminous paths with magenta pulses on critical events. The left 5 of 12 columns hold an oversized Space Grotesk headline stacked in three tight lines — "Describe it. / The swarm / builds it." — over a mono micro-label "EMERGENT-BOLT // AGENT ORCHESTRATION" and one cyan primary CTA pinned beneath the type block. A translucent HUD strip along the bottom edge shows live mono readouts — AGENTS 12 · SWARM ACTIVE · SANDBOX READY · TOKENS 48,209 — as real UI, not decoration. No centred headline, no subtext paragraph, no blue button, no blob.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: cinematic Hero Dimensionality: webgl

Landing Hero Motion Brief

• Focal subject: The volumetric cyan swarm core with orbiting agent nodes on thin luminous paths.
• Input→transformation→outcome thesis: On load, the swarm core ignites and agent nodes begin orbiting; light sweeps travel along edges; magenta pulses fire on critical events; the HUD strip readouts tick — communicating that describing an idea sets the swarm in motion to build it.
• Motion vocabulary: 900ms scroll-scrubbed parallax between hero layers; continuous slow orbit of the node graph with light sweeps; agent status changes pulse once in cyan (400ms) and settle; token counters tick with monospace numerals; type reveals line-by-line on hero load.
• Composed first frame: Dark void; swarm core right at 55% width; three-line headline left; mono micro-label above; cyan CTA beneath; HUD strip along bottom edge.
• Reduced-motion state: All continuous motion pauses; static node graph and readable log stream remain; type fully visible.

Landing Hero 3D Scene Brief — DIRECTION-DERIVED A real-time WebGL/R3F scene: one crafted volumetric swarm core (glowing, cyan) with orbiting agent nodes on thin luminous paths, magenta pulses on critical events, and light sweeps along edges. The scene shows the product's defining state — a swarm executing — and is the hero subject occupying the right 55% of the viewport.

9. Non-Functional Requirements

• NFR-1 — Durable state (required_inference): Application-owned persistent data (accounts, builds, agent/swarm configuration, sandboxes, token records, repositories) persists across sessions in MariaDB.
• NFR-2 — AI gateway (required_inference): All model-provider calls route through LiteLLM; LiteLLM uses its own PostgreSQL, separate from application-owned storage.
• NFR-3 — Shared coordination (required_inference): Redis provides shared caching, run-state coordination, and background job/queue coordination for generation runs.
• NFR-4 — Background automation (required_inference): Generation runs execute asynchronously with live status surfaced to Builders and telemetry to Operators.
• NFR-5 — Access control (required_inference): Protected Builder and Operator destinations require an authenticated session; Landing, Sign Up, and Login are anonymous.
• NFR-6 — High-quality output (explicit): The platform must match Emergent's high-quality output standard.
• NFR-7 — Accessibility (explicit, creative direction): Readable text and controls stay whole at 375px, 768px, and 1280px; reduced-motion provides a usable static arrangement.

10. Tech Stack

• Frontend: React application UI.
• Backend: Shared FastAPI process for application APIs and domain modules (identity, builds, orchestration, sandbox/environment, tokens, repositories).
• Application database: MariaDB for application-owned persistent data.
• Cache/coordination: Redis for shared caching, state, queue, and coordination.
• Model gateway: LiteLLM for the backend's model-provider calls.
• Gateway database: PostgreSQL supporting LiteLLM; separate from application-owned storage.
• Deployment: docker-compose with the services above (backend, database, frontend, litellm, postgres, redis).

11. Assumptions and Constraints

• Constraint (explicit): The platform must match Emergent's processes, workflows, architecture, internal processes, agents, swarms, sandbox, environment, high-quality output, tokens, and repositories.
• Constraint (explicit): Additional functions and features must come from Bolt and Lovable.
• Assumption (required_inference): Builders self-enroll; Platform Operators are provisioned or invited.
• Assumption (required_inference): Identity is application-owned; protected destinations require an authenticated session.
• Assumption (required_inference): Generation runs execute asynchronously via background automation.
• Assumption: The generic indigo/blue-on-white SaaS template is forbidden; the dark cinematic direction is authoritative.

12. Glossary

• Builder: A user who describes an app idea and expects the platform to plan, generate, and run it.
• Platform Operator: A user responsible for configuring agents and swarms and overseeing provisioning, tokens, and repositories.
• Agent: An autonomous unit that performs generation work.
• Swarm: A coordinated group of agents executing a generation run.
• Sandbox: An isolated environment in which the generated application runs.
• Environment configuration: The settings for a sandbox.
• Token: A unit of model consumption metered by the platform.
• Repository: The code repository produced for a project.
• Generation run: The asynchronous process from description to generated output.
• LiteLLM: The model-provider gateway used by the backend.