# king-defender/ai-analyst architecture

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

- Interactive diagram: https://gitdiagram.com/king-defender/ai-analyst
- Repository: https://github.com/king-defender/ai-analyst

## Overview

##### Project type and purpose
- This is a full-stack AI-powered analyst MVP.
- Frontend: React + TypeScript web app for uploading pitch decks and viewing results.
- Backend: Python FastAPI service exposing REST endpoints for ingestion, benchmarking, risk assessment, memo generation.
- ML pipeline: standalone Python modules (in ml/) that orchestrate document processing, risk engines, memo generation, using Vertex AI/LLM.
- Infrastructure: GCP services (Vision API, Vertex AI, BigQuery, Cloud Storage, Firestore) and Docker for local/dev environments.

##### File structure
- Top level:
- frontend/ – Next.js + React + Tailwind code, components, hooks, tests.
- backend/ – FastAPI app with routers/, services/, models/, schemas/, configuration, Dockerfiles, tests.
- ml/ – ML pipeline modules, prompts, tests.
- infra/ – SQL schemas/queries for BigQuery, Firestore emulator Dockerfile.
- docs/, scripts/, sample_data/ for documentation, automation, examples.
- Patterns:
- Backend uses layered architecture: routers → services → core/config.
- Frontend follows component-based pattern with hooks and API abstraction in lib/api.ts.
- ML pipeline is modular: document_processing, risk_assessment, memo_generation, orchestrated via ml/main.py.
- Config and deployment:
- Docker Compose for dev environment.
- Dockerfiles for backend and frontend.
- GitHub Actions CI in .github/workflows.

##### README for additional insights
- Tech stack and service dependencies are documented.
- GCP services interplay: Cloud Vision for OCR, BigQuery for data warehousing, Vertex AI/Vector Search, Cloud Storage for file storage, Firestore for low-latency storage.

##### Final recommendations
- Backend sub-module only if it’s relevant to high-level flows (e.g., OCR, Benchmark Service, Risk Service).
- Maintain numbering/order for job workflows (1→2→3…) to aid readability.
- Review with domain experts to ensure all interactions (retry logic, error handling) are documented separately if needed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)"
        User["User"]:::ui
    end

    %% Frontend Layer
    subgraph "Frontend (Next.js)" 
        FrontendApp["Frontend (Next.js/React UI)"]:::ui
        Page["Page Entry (upload & results)"]:::ui
        FileUpload["FileUpload"]:::ui
        JobTracker["JobTracker"]:::ui
        BenchmarkDisplay["BenchmarkDisplay"]:::ui
        RiskDisplay["RiskDisplay"]:::ui
        MemoViewer["MemoViewer"]:::ui
        ApiClient["Frontend API Client"]:::ui
        UseFileUpload["useFileUpload Hook"]:::ui
        UseJobStatus["useJobStatus Hook"]:::ui
    end

    %% Backend Layer
    subgraph "Backend (FastAPI)"
        MainEntry["backend/main.py"]:::api
        subgraph "Routers"
            DocsRouter["Documents Router"]:::api
            AnalysisRouter["Analysis Router"]:::api
            JobsRouter["Jobs Router"]:::api
            MemosRouter["Memos Router"]:::api
        end
        subgraph "Services"
            FileService["file_service"]:::api
            OCRService["ocr_service"]:::api
            BenchmarkService["benchmark_service"]:::api
            RiskService["risk_service"]:::api
            MemoService["memo_service"]:::api
            ParsingService["parsing_service"]:::api
            JobService["job_service"]:::api
        end
        Config["config.py"]:::api
    end

    %% ML Pipeline Layer
    subgraph "ML Pipeline (Python)"
        Orchestrator["ml/main.py"]:::ml
        DocumentProc["document_processing"]:::ml
        RiskAssess["risk_assessment"]:::ml
        RiskEngine["risk_engine"]:::ml
        MemoGen["memo_generation"]:::ml
        Templates["prompt templates"]:::ml
    end

    %% GCP Services
    subgraph "GCP Services"
        VisionAPI["Cloud Vision API"]:::cloud
        VertexAI["Vertex AI / LLM & Vector Search"]:::cloud
        BigQueryService["BigQuery Service"]:::cloud
        CloudStorage["Cloud Storage"]:::cloud
        FirestoreService["Firestore"]:::cloud
    end

    %% Data Stores
    subgraph "Data Stores"
        BigQueryDB["BigQuery Dataset"]:::data
        FirestoreDB["Firestore DB"]:::data
        StorageBucket["Storage Bucket"]:::data
    end

    %% Client to Frontend
    User -->|"1. interacts with"| Page
    Page -->|uses| FileUpload
    Page -->|uses| JobTracker
    Page -->|displays| BenchmarkDisplay
    Page -->|displays| RiskDisplay
    Page -->|displays| MemoViewer
    FileUpload -->|calls| UseFileUpload
    JobTracker -->|calls| UseJobStatus
    UseFileUpload -->|HTTP/REST| ApiClient
    UseJobStatus -->|HTTP/REST| ApiClient

    %% Frontend to Backend
    ApiClient -->|"POST /documents"| DocsRouter
    ApiClient -->|"GET /analysis"| AnalysisRouter
    ApiClient -->|"GET /jobs"| JobsRouter
    ApiClient -->|"GET /memos"| MemosRouter

    %% Backend routing to services
    MainEntry --> DocsRouter
    MainEntry --> AnalysisRouter
    MainEntry --> JobsRouter
    MainEntry --> MemosRouter
    DocsRouter --> FileService
    DocsRouter --> OCRService
    AnalysisRouter --> BenchmarkService
    AnalysisRouter --> RiskService
    AnalysisRouter --> MemoService
    JobsRouter --> JobService
    MemosRouter --> MemoService
    JobService -->|async| Orchestrator
    FileService -->|stores file| StorageBucket
    OCRService -->|OCR| VisionAPI
    BenchmarkService -->|queries| BigQueryService
    RiskService -->|calls| VertexAI
    MemoService -->|calls| VertexAI
    AnalysisRouter --> ParsingService

    %% Backend storage
    MainEntry --> Config
    MainEntry --> FirestoreService
    MainEntry --> StorageBucket

    %% ML Pipeline Flow
    Orchestrator --> DocumentProc
    DocumentProc --> RiskAssess
    RiskAssess --> RiskEngine
    RiskEngine --> MemoGen
    MemoGen --> Templates
    MemoGen --> VertexAI

    %% Data services connections
    BigQueryService --> BigQueryDB
    FirestoreService --> FirestoreDB
    CloudStorage --> StorageBucket

    %% Classes and Styles
    classDef ui fill:#D6E9FE,stroke:#6CA0DC,color:#034A78;
    classDef api fill:#DFF6E0,stroke:#3E8E41,color:#1F5E20;
    classDef ml fill:#F3E6FF,stroke:#A76BCF,color:#5A2A6B;
    classDef cloud fill:#F0F0F0,stroke:#A0A0A0,color:#444444;
    classDef data fill:#FFEFD6,stroke:#D39E3C,color:#7F5217;

    %% Click Events Frontend
    click FrontendApp "https://github.com/king-defender/ai-analyst/tree/main/frontend/"
    click Page "https://github.com/king-defender/ai-analyst/blob/main/frontend/src/app/page.tsx"
    click FileUpload "https://github.com/king-defender/ai-analyst/blob/main/frontend/src/components/upload/FileUpload.tsx"
    click JobTracker "https://github.com/king-defender/ai-analyst/blob/main/frontend/src/components/status/JobTracker.tsx"
    click BenchmarkDisplay "https://github.com/king-defender/ai-analyst/blob/main/frontend/src/components/benchmarks/BenchmarkDisplay.tsx"
    click RiskDisplay "https://github.com/king-defender/ai-analyst/blob/main/frontend/src/components/risks/RiskDisplay.tsx"
    click MemoViewer "https://github.com/king-defender/ai-analyst/blob/main/frontend/src/components/memo/MemoViewer.tsx"
    click UseFileUpload "https://github.com/king-defender/ai-analyst/blob/main/frontend/src/hooks/useFileUpload.ts"
    click UseJobStatus "https://github.com/king-defender/ai-analyst/blob/main/frontend/src/hooks/useJobStatus.ts"
    click ApiClient "https://github.com/king-defender/ai-analyst/blob/main/frontend/src/lib/api.ts"

    %% Click Events Backend
    click MainEntry "https://github.com/king-defender/ai-analyst/blob/main/backend/main.py"
    click DocsRouter "https://github.com/king-defender/ai-analyst/blob/main/backend/app/routers/documents.py"
    click AnalysisRouter "https://github.com/king-defender/ai-analyst/blob/main/backend/app/routers/analysis.py"
    click JobsRouter "https://github.com/king-defender/ai-analyst/blob/main/backend/app/routers/jobs.py"
    click MemosRouter "https://github.com/king-defender/ai-analyst/blob/main/backend/app/routers/memos.py"
    click FileService "https://github.com/king-defender/ai-analyst/blob/main/backend/app/services/file_service.py"
    click OCRService "https://github.com/king-defender/ai-analyst/blob/main/backend/app/services/ocr_service.py"
    click BenchmarkService "https://github.com/king-defender/ai-analyst/blob/main/backend/app/services/benchmark_service.py"
    click RiskService "https://github.com/king-defender/ai-analyst/blob/main/backend/app/services/risk_service.py"
    click MemoService "https://github.com/king-defender/ai-analyst/blob/main/backend/app/services/memo_service.py"
    click ParsingService "https://github.com/king-defender/ai-analyst/blob/main/backend/app/services/parsing_service.py"
    click JobService "https://github.com/king-defender/ai-analyst/blob/main/backend/app/services/job_service.py"
    click Config "https://github.com/king-defender/ai-analyst/blob/main/backend/app/core/config.py"

    %% Click Events ML
    click Orchestrator "https://github.com/king-defender/ai-analyst/blob/main/ml/main.py"
    click DocumentProc "https://github.com/king-defender/ai-analyst/blob/main/ml/pipeline/document_processing.py"
    click RiskAssess "https://github.com/king-defender/ai-analyst/blob/main/ml/pipeline/risk_assessment.py"
    click RiskEngine "https://github.com/king-defender/ai-analyst/blob/main/ml/pipeline/risk_engine.py"
    click MemoGen "https://github.com/king-defender/ai-analyst/blob/main/ml/pipeline/memo_generation.py"
    click Templates "https://github.com/king-defender/ai-analyst/blob/main/ml/prompts/templates.py"

    %% Click Events Infra
    click BigQueryService "https://github.com/king-defender/ai-analyst/tree/main/infra/bigquery/schemas/"
    click BigQueryDB "https://github.com/king-defender/ai-analyst/blob/main/infra/bigquery/queries/calculate_benchmarks.sql"
    click FirestoreService "https://github.com/king-defender/ai-analyst/blob/main/infra/firestore-emulator.Dockerfile"
    click Orchestrator "https://github.com/king-defender/ai-analyst/blob/main/docker-compose.dev.yml"
    click JobService "https://github.com/king-defender/ai-analyst/blob/main/.github/workflows/comprehensive-tests.yml"
```
