Async Processing Architecture Diagram

Visual overview of the SQS-based async processing pipeline — from bot completion through settlement and report generation.

flowchart TB
  subgraph API["Fargate API (apps/api)"]
    BotComplete["completeInterview<br/>bot-interview.service.ts"]
    BotFail["failInterview<br/>bot-interview.service.ts"]
    SQSProd["sqs.service.ts<br/>publishInterview* / publishReportGenerate"]
    SettleSvc["settlement.service.ts<br/>settleCompletedInterview / settleFailedInterview"]
    ReportSvc["report-generation.service.ts<br/>generateReport"]
  end

  subgraph SQS["Amazon SQS"]
    ICQ["InterviewCompleted queue<br/>infra/queues.ts"]
    ICDLQ["InterviewCompletedDlq<br/>14d retention"]
    RGQ["ReportGenerate queue<br/>infra/queues.ts"]
    RGDLQ["ReportGenerateDlq<br/>14d retention"]
  end

  subgraph Lambda["AWS Lambda (apps/functions)"]
    ICHandler["sophia-{stage}-interview-completed<br/>interview-completed.handler"]
    RGHandler["sophia-{stage}-report-generate<br/>report-generate.handler"]
    Wrapper["createSqsConsumer<br/>sqs-consumer.ts"]
  end

  subgraph Data["Data & external"]
    Mongo[(MongoDB)]
    OpenAI[(OpenAI API)]
  end

  BotComplete -->|"status COMPLETED + timing"| Mongo
  BotFail -->|"status FAILED"| Mongo
  BotComplete --> SQSProd
  BotFail --> SQSProd

  SQSProd -->|"JSON: completed or type interview.failed"| ICQ
  ICQ -->|"batch 10, partialResponses"| ICHandler
  ICHandler --> Wrapper
  Wrapper --> SettleSvc
  SettleSvc --> Mongo
  SettleSvc -->|"first settle only: publishReportGenerate"| SQSProd
  SQSProd -->|"JSON: interviewId, organizationId"| RGQ

  ICQ -.->|"maxReceiveCount 3"| ICDLQ

  RGQ -->|"batch 1, partialResponses"| RGHandler
  RGHandler --> Wrapper
  Wrapper --> ReportSvc
  ReportSvc --> Mongo
  ReportSvc --> OpenAI
  RGQ -.->|"maxReceiveCount 3"| RGDLQ

  classDef queue fill:#fef3c7,stroke:#d97706
  classDef dlq fill:#fee2e2,stroke:#dc2626
  classDef lambda fill:#dbeafe,stroke:#2563eb
  class ICQ,RGQ queue
  class ICDLQ,RGDLQ dlq
  class ICHandler,RGHandler lambda