Technical Specifications & Architecture

A comprehensive guide to the underlying database schemas, API architecture, design systems, and orchestration flow of Build Spec Studio.

Database Schemas & Models

Build Spec Studio utilizes MongoDB as its primary persistence engine, storing project states, active specifications, LLM conversation logs, and resources configurations.

1. Projects Collection (`projects`)

Stores complete states and specs generated for each project.

{
  "_id": "ObjectId",
  "id": "string (Unique client-generated UUID)",
  "name": "string (Project Name)",
  "description": "string (Initial description / user prompt)",
  "category": "SoftwareCategory | null",
  "createdAt": "ISOString",
  "updatedAt": "ISOString",
  "specification": {
    "markdown": "string (Full generated markdown PRD)",
    "sections": [
      {
        "id": "string",
        "title": "string",
        "content": "string",
        "confidence": "number (0-100)",
        "lastUpdated": "ISOString",
        "order": "number"
      }
    ],
    "lastUpdated": "ISOString"
  },
  "conversation": [
    {
      "id": "string",
      "role": "'user' | 'assistant' | 'system'",
      "content": "string",
      "timestamp": "ISOString",
      "questions": "AIQuestion[]",
      "answers": "Record<string, string>",
      "tokenCount": "number",
      "isChallenge": "boolean"
    }
  ],
  "knowledgeGraph": {
    "nodes": {
      "nodeId": {
        "id": "string",
        "topic": "string",
        "confidence": "number",
        "importance": "number",
        "status": "'unknown' | 'partial' | 'resolved' | 'challenged'",
        "dependencies": "string[]",
        "assumptions": "string[]",
        "missingInfo": "string[]",
        "resolvedValue": "string | null",
        "category": "string"
      }
    }
  },
  "tokenUsage": {
    "totalTokens": "number",
    "currentContextSize": "number",
    "estimatedCost": "number",
    "sessionTokens": "number",
    "maxContextSize": "number"
  },
  "completeness": {
    "overall": "number (0-100)",
    "categories": "Record<string, number>",
    "remainingUnknowns": "string[]",
    "aiConfidence": "number"
  },
  "config": {
    "port": "number",
    "dbName": "string",
    "dbUrl": "string",
    "gcpUrl": "string",
    "gitRepoUrl": "string",
    "gitInitialized": "boolean",
    "resourcesProvisioned": "boolean",
    "customSettings": "Record<string, any>"
  }
}

2. Project Resources Collection (`project_resources`)

Tracks container configurations, live deployment logs, custom domains, and DNS states.

{
  "_id": "ObjectId",
  "projectId": "string (foreign key mapping to project.id)",
  "cloudRun": {
    "status": "'idle' | 'deploying' | 'active'",
    "serviceUrl": "string",
    "region": "string",
    "memory": "string",
    "cpu": "string",
    "scaleMin": "number",
    "scaleMax": "number",
    "logs": "string[]"
  },
  "domain": {
    "name": "string",
    "status": "'idle' | 'pending_dns' | 'verifying' | 'active'",
    "dnsRecords": [
      {
        "type": "string (A, CNAME, TXT)",
        "host": "string",
        "value": "string"
      }
    ],
    "sslStatus": "'none' | 'issuing' | 'active'"
  }
}

API Reference

The application exposes RESTful endpoints supporting JSON serialization:

Method	Endpoint	Description
GET	`/api/projects`	Lists all projects in the workspace database.
POST	`/api/projects`	Upserts project state (inserts new or updates existing).
DELETE	`/api/projects?id=[ID]`	Deletes project and its specification from database.
GET	`/api/resources?projectId=[ID]`	Checks connectivity status and loads active cloud resources.
POST	`/api/resources`	Executes actions like Whitelist IP, Create User, Deploy Cloud Run.

System Flow & Architecture

1. Ambiguity Reduction Chat

When you converse with the AI, the engine continuously structures the specifications and scores the completeness. It generates inline structured questions to resolve system gaps.

2. Infrastructure Provisioning Pipeline

The `/resources` page includes a Console-first deployment wizard for GitHub → Cloud Build → Cloud Run auto-deploy. Per-project Cloud Run services use the real Google Cloud Run API when GCP credentials are configured.