Rapto AI System Design: Inside Our Distributed Meeting Accountability Architecture

sequenceDiagram
  autonumber
  actor User as Web / Mobile Client
  participant Nginx as NGINX Reverse Proxy
  participant API as Node.js API Gateway
  participant Redis as Redis 7 (Rate Limit & Cache)
  participant Postgres as PostgreSQL (Prisma ORM)
  participant Worker as BullMQ Queue

  User->>Nginx: POST /api/v1/meetings/{id}/process (Bearer JWT)
  Nginx->>Nginx: Rate Limit Check (Zone: api_limit)
  Nginx->>API: Proxy to http://api:5000
  API->>API: Validate JWT Signature & Expiry
  API->>Redis: Check User Session & Permissions Cache
  alt Cache Miss
    API->>Postgres: Query TeamMember & Role (Prisma RLS)
    API->>Redis: Cache Session (TTL: 300s)
  end
  API->>Postgres: Verify Resource Ownership (teamId match)
  API->>Worker: Enqueue Job into 'extract.queue'
  API->>Postgres: Update MeetingStatus to 'PROCESSING'
  API-->>User: HTTP 202 Accepted { jobId: "job_9841fbc", status: "PROCESSING" }

sequenceDiagram
  autonumber
  participant Worker as Node.js BullMQ Worker
  participant AIPipeline as Python FastAPI (:8001)
  participant OpenAI as OpenAI API

  Worker->>Worker: Prepare ExtractRequest Payload
  Worker->>Worker: Attach 'X-Service-Key' Header (API_SHARED_SECRET)
  Worker->>AIPipeline: POST /api/v1/extract (JSON Payload)
  AIPipeline->>AIPipeline: verify_internal_service_key() (Constant-Time Compare)
  alt Key Invalid / Missing
    AIPipeline-->>Worker: HTTP 401 Unauthorized
  end
  AIPipeline->>AIPipeline: Chunk Transcript & Tokenize (tiktoken)
  AIPipeline->>OpenAI: Concurrent Structured Extraction (GPT-4o)
  OpenAI-->>AIPipeline: Structured JSON Entities
  AIPipeline->>AIPipeline: Cross-Chunk Deduplication (threshold: 0.70)
  AIPipeline-->>Worker: HTTP 200 OK (ExtractResponse Model)

# Python FastAPI Inter-Service Authentication Dependency
async def verify_internal_service_key(
    x_service_key: Optional[str] = Header(None, alias="X-Service-Key")
) -> None:
    if not x_service_key:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Missing X-Service-Key authentication header"
        )
    if not secrets.compare_digest(x_service_key, settings.API_SHARED_SECRET):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid service key credentials"
        )

sequenceDiagram
  autonumber
  actor Engineer as Engineer (Dave)
  participant Meet as Video Conference (Google Meet / Zoom)
  participant Recall as Recall.ai Recording Bot
  participant API as Node.js API Gateway
  participant Worker as BullMQ Worker Cluster
  participant PythonAI as Python AI Pipeline
  participant DB as PostgreSQL & MongoDB
  participant Linear as Linear / Jira Backlog
  participant Slack as Slack Channel

  Engineer->>Meet: "I'll benchmark the connection pool before Thursday's release"
  Meet-->>Recall: Audio Stream Captured
  Meet->>Meet: Meeting Concludes
  Recall->>API: Webhook: bot.status_change (DONE + Transcript URL)
  API->>Worker: Enqueue to 'transcribe.queue'
  Worker->>DB: Store Diarized Transcript into MongoDB
  Worker->>Worker: Enqueue to 'extract.queue'
  Worker->>PythonAI: POST /extract (Cleaned Transcript)
  PythonAI->>PythonAI: Chunking + Structured Entity Extraction
  PythonAI-->>Worker: Extracted Commitment: { Actor: "Dave", Action: "Benchmark connection pool", Deadline: "2026-09-04" }
  Worker->>DB: Resolve Speaker Dave -> TeamMember usr_982 & Insert Commitment (PENDING)
  Worker->>Worker: Enqueue 'integrate.queue' & 'resolve.queue'
  Worker->>Linear: POST /issues (Create Issue: "Benchmark connection pool")
  Linear-->>Worker: Issue Created (ENG-842)
  Worker->>DB: Save ExternalCommitmentMapping (Jira/Linear ID: ENG-842)
  Worker->>Slack: Send Interactive Block Kit Card to #eng-backend

  Note over Engineer,Meet: Next Standup (3 Days Later)
  Engineer->>Meet: "That connection pool benchmark is done, latency dropped 40%"
  Meet-->>Recall: Audio Stream Captured
  Recall->>API: Webhook: Transcript Ready
  Worker->>PythonAI: POST /resolve (Unresolved Commitments + Current Transcript)
  PythonAI->>PythonAI: Vector Similarity Match (0.89 Confidence)
  PythonAI-->>Worker: Resolution: { commitmentId: "cmt_104", status: "FULFILLED" }
  Worker->>DB: Update Commitment status = 'FULFILLED'
  Worker->>DB: Recalculate TeamHealthScore (Recency-Weighted Velocity)
  Worker->>Slack: Update Slack Card: FULFILLED ✓

graph TD
  subgraph Security_Architecture [Defense-in-Depth Security Layers]
    L1[Layer 1: Edge TLS 1.3 & NGINX Rate Limiting]
    L2[Layer 2: JWT Access Token 15m + Rotating HttpOnly Refresh Token 30d]
    L3[Layer 3: Prisma ORM Tenant Middleware auto-injecting teamId]
    L4[Layer 4: PostgreSQL Row-Level Security RLS Policies]
    L5[Layer 5: AES-256-GCM Envelope Encryption for OAuth Tokens]
    L6[Layer 6: Zero-Data-Retention Agreements on LLM Pipelines]
  end

  L1 --> L2
  L2 --> L3
  L3 --> L4
  L4 --> L5
  L5 --> L6

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Why did Rapto AI split the backend between Node.js and Python?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Node.js with TypeScript is uniquely suited for high-throughput, I/O-intensive operations like handling hundreds of concurrent OAuth webhook integrations, managing real-time Socket.io connections, and serving low-latency REST APIs. Python with FastAPI provides first-class native tooling for tokenization, chunking, and AI model orchestration."
      }
    },
    {
      "@type": "Question",
      "name": "How does Rapto AI ensure multi-tenant data isolation?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Rapto AI implements defense-in-depth tenant isolation: application middleware, Prisma ORM query extensions auto-injecting teamId filters, PostgreSQL Row-Level Security (RLS), and namespace-scoped Redis keys."
      }
    }
  ]
}