# adarshh9/docqa-aws architecture

> Architecture diagram of the GitHub repository adarshh9/docqa-aws, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adarshh9/docqa-aws
- Repository: https://github.com/adarshh9/docqa-aws

## Overview

##### Project type and purpose
- This is a microservices‐based Document Q&A system (“DocQA AI Agent”) built on FastAPI, Docker, and machine learning.
- Its goal is to let users upload PDF/TXT documents, extract content, build embeddings, and answer questions via an LLM, all orchestrated by an API gateway.

##### File structure
- Top-level services (each with its own Dockerfile, main.py, requirements.txt):
- api-gateway
- ingestion-service
- vector-service
- llm-service
- memory-service
- Shared code in `shared` (models.py, utils.py) used by multiple services
- Orchestration via docker-compose.yml
- Helpers/tests: `qdrant_debug.py`, `workspace_dumper.py`, `test_compete_system.py`
- A simple `index.html` and package.json (likely for a minimal frontend or health checks)

##### README for additional insights
- Ports: 8000 (API Gateway), 8001–8004 for individual services
- Key features: document upload, embedding, similarity search, session memory, LLM generation
- Production notes: swap in Redis/PostgreSQL, external LLMs, proper vector DBs, observability

##### Detailed capture of essential elements
- Shared code as a package imported by each service
- Health check endpoints on each service

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Client (Browser/CLI)"]:::client

    %% Application Cluster
    subgraph "Application Cluster" 
        direction TB
        APIGateway["API Gateway\n(Port 8000)\n/endpoints: /upload, /ask"]:::api
        Ingestion["Ingestion Service\n(Port 8001)\n/extract"]:::core
        Vector["Vector Service\n(Port 8002)\n/embed, /search"]:::core
        Memory["Memory Service\n(Port 8003)\n/history"]:::core
        LLM["LLM Service\n(Port 8004)\n/generate"]:::core
        SharedLib["Shared Library\n(models.py, utils.py)"]:::shared
    end

    %% External Resources
    subgraph "External Resources" 
        direction TB
        VectorDB["Vector DB\n(Qdrant/Redis)"]:::ext
        SessionStore["Session Store\n(Redis/PostgreSQL)"]:::ext
        ExternalLLM["External LLM API\n(OpenAI/Anthropic)"]:::ext
    end

    %% Orchestration
    DockerCompose["Docker Compose\n(docker-compose.yml)"]:::orch

    %% Helpers & Tests
    DebugHelpers["Debug & Helpers\n(qdrant_debug.py,\nworkspace_dumper.py)"]:::tools
    IntegrationTests["Integration Tests\n(test_compete_system.py)"]:::tools
    FrontendStub["Frontend Stub\n(index.html,\npackage.json)"]:::client

    %% Connections
    Client -->|"HTTP" | APIGateway
    APIGateway -->|"POST /upload"| Ingestion
    Ingestion -->|"chunks"| Vector
    APIGateway -->|"GET /ask"| Vector
    APIGateway -->|"read/write"| Memory
    APIGateway -->|"prompt"| LLM
    LLM -->|"calls"| ExternalLLM
    Vector -->|"store/search"| VectorDB
    Memory -->|"persist"| SessionStore

    %% Shared Library Imports
    SharedLib --> APIGateway
    SharedLib --> Ingestion
    SharedLib --> Vector
    SharedLib --> Memory
    SharedLib --> LLM

    %% Orchestration connections
    DockerCompose --> APIGateway
    DockerCompose --> Ingestion
    DockerCompose --> Vector
    DockerCompose --> Memory
    DockerCompose --> LLM

    %% Helpers & Tests usage
    DebugHelpers --> VectorDB
    IntegrationTests --> APIGateway
    FrontendStub --> APIGateway

    %% Click Events
    click APIGateway "https://github.com/adarshh9/docqa-aws/blob/main/api-gateway/main.py"
    click Ingestion "https://github.com/adarshh9/docqa-aws/blob/main/ingestion-service/main.py"
    click Vector "https://github.com/adarshh9/docqa-aws/blob/main/vector-service/main.py"
    click Memory "https://github.com/adarshh9/docqa-aws/blob/main/memory-service/main.py"
    click LLM "https://github.com/adarshh9/docqa-aws/blob/main/llm-service/main.py"
    click SharedLib "https://github.com/adarshh9/docqa-aws/blob/main/shared/models.py"
    click DockerCompose "https://github.com/adarshh9/docqa-aws/blob/main/docker-compose.yml"
    click FrontendStub "https://github.com/adarshh9/docqa-aws/blob/main/index.html"
    click DebugHelpers "https://github.com/adarshh9/docqa-aws/blob/main/qdrant_debug.py"
    click IntegrationTests "https://github.com/adarshh9/docqa-aws/blob/main/test_compete_system.py"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:1px;
    classDef api fill:#bbf,stroke:#1f77b4,stroke-width:1px;
    classDef core fill:#8f8,stroke:#2ca02c,stroke-width:1px;
    classDef shared fill:#ffeb3b,stroke:#d4a017,stroke-width:1px;
    classDef ext fill:#ddd,stroke:#888,stroke-dasharray: 5 5,stroke-width:1px;
    classDef orch fill:#ffb,stroke:#ff7f0e,stroke-width:1px;
    classDef tools fill:#ececec,stroke:#666,stroke-width:1px;
```
