# tabiya-tech/compass architecture

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

- Interactive diagram: https://gitdiagram.com/tabiya-tech/compass
- Repository: https://github.com/tabiya-tech/compass

## Overview

##### Project type and purpose
- This is a full-stack AI chatbot (“Compass”) for job seekers, comprising:
– A Python/FastAPI-based backend that orchestrates LLM calls, vector search, state management and multiple domain services (feedback, invitations, metrics, sensitive-data filtering, etc.).
– Two frontends:
- “frontend” – a legacy Next.js proof-of-concept chat UI
- “frontend-new” – the production-grade React/Next.js TypeScript app with Firebase-based auth and a rich component library
– An IaC layer (Pulumi scripts) that deploys all services to AWS (and some GCP identity resources).

##### File structure
- Top level:
– backend/ – Python service
– frontend-new/ – Next.js α React UI
– frontend/ – POC chat UI
– iac/ – Pulumi infrastructure code
- backend/
– app/ – core; server.py (FastAPI entrypoint), modules for agent orchestration, conversation memory, vector search, user/feedback/invitations/metrics routes, persistence stores
– common_libs/ – shared utilities (LLM callers, logging, retry, test helpers)
– evaluation_tests/ – end-to-end and unit tests for each agent and pipeline
– scripts/ – maintenance and data-prep scripts (embeddings, migrations, export/import)
- frontend-new/
– src/app/ – global wrappers (storage, routing, viewport)
– src/auth/ – Firebase config, service factories, auth UI pages
– src/chat/ – chat components + ChatService wrapper for API calls
– src/… – experiences drawer, reports, feedback forms, metrics, sensitive-data forms, user preferences, theming, utilities, global error handling
- iac/
– subfolders by stack (auth, aws-ns, backend, frontend, dns, environment, realm, common)
– each contains Pulumi.yaml + Python deploy scripts

##### Parse the README for additional insights
- Compass helps job-seekers extract skills and experiences via AI agents.
- Two frontend flavors exist until the new UI is complete.
- CI/CD is defined in .github/workflows for backend, frontend, config and deploy.
- run-before-merge.sh orchestrates lint/build/test across all subprojects.

##### Detail level
– Don’t omit any persistence store (MongoDB, JSON store, vector store)
– Include the IAC pipelines feeding into the deployment of front/back

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "User Layer"
    Browser["User's Browser"]:::external
  end

  subgraph "Frontend Layer"
    subgraph "Legacy Frontend"
      POC["POC Chat UI"]:::frontend
    end
    subgraph "New Frontend"
      NewUI["Production-grade Next.js/React App"]:::frontend
      AuthUI["Firebase Auth UI"]:::frontend
    end
    Firebase["Firebase Auth & IDP"]:::external
  end

  Browser -->|"HTTPS"| POC
  Browser -->|"HTTPS"| NewUI
  NewUI -->|"Auth via Firebase"| AuthUI
  AuthUI -->|"↔"| Firebase

  POC -->|"HTTPS"| APIGW["API Gateway / CloudFront"]:::infra
  NewUI -->|"HTTPS"| APIGW

  subgraph "Backend Layer"
    Backend["FastAPI Backend"]:::backend
    subgraph "Agents & Pipelines"
      AD["Agent Director"]:::backend
      CEA["Collect Experiences Agent"]:::backend
      QNA["Q&A Agent"]:::backend
      SEA["Skill Explorer Agent"]:::backend
      WA["Welcome Agent"]:::backend
    end
    CMM["Conversation Memory Manager"]:::backend
    subgraph "Persistence Stores"
      Mongo["MongoDB Store"]:::datastore
      InMem["In-Memory Store"]:::datastore
      JSONStore["JSON Store"]:::datastore
      TXTStore["TXT Store"]:::datastore
      MDStore["Markdown Store"]:::datastore
    end
    subgraph "Vector Search Module"
      ESCOEnt["ESCO Entities"]:::backend
      Emb["Embeddings Model"]:::backend
      ESSvc["Entity Search Service"]:::backend
      SSSvc["Similarity Search Service"]:::backend
      OccRoutes["Occupation Search Routes"]:::backend
      SkillRoutes["Skill Search Routes"]:::backend
    end
    FBRoutes["Feedback Routes"]:::backend
    FBRepo["Feedback Repository"]:::backend
    FBServ["Feedback Service"]:::backend
    InvRoutes["Invitations Routes"]:::backend
    InvRepo["Invitations Repository"]:::backend
    MSRoutes["Metrics Routes"]:::backend
    MSRepo["Metrics Repository"]:::backend
    MSRec["Metrics Recorder"]:::backend
    MSServ["Metrics Service"]:::backend
    SensFilter["Sensitive Data Filter"]:::backend
    DepInject["Server Dependencies Injector"]:::backend
    Config["App & Server Config"]:::backend
    LLMCaller["LLM Caller (OpenAI/Anthropic)"]:::external
    Sentry["Sentry"]:::external
    Backend -->|"uses"| DepInject
    Backend -->|"loads"| Config
    Backend -->|"calls"| LLMCaller
    Backend -->|"logs to"| Sentry
    Backend -->|"routes via"| AD
    Backend -->|"manages"| CMM
    Backend --> Mongo
    Backend --> InMem
    Backend --> JSONStore
    Backend --> TXTStore
    Backend --> MDStore
    Backend --> ESCOEnt
    Backend --> ESSvc
    Backend --> SSSvc
    Backend --> FBRoutes
    Backend --> FBServ
    Backend --> InvRoutes
    Backend --> MSServ
    Backend --> SensFilter
  end

  APIGW -->|"HTTP Requests"| Backend

  subgraph "Data & External Services"
    MongoDB["MongoDB Atlas"]:::datastore
    VectorDB["Elasticsearch/Vector DB"]:::datastore
    LLMExt["LLM Providers"]:::external
    SentryExt["Sentry"]:::external
    S3["S3 / Object Storage"]:::external
    LLMCaller --> LLMExt
    ESCOEnt --> VectorDB
    Emb --> VectorDB
    Backend --> S3
  end

  subgraph "Infrastructure & CI-CD"
    Pulumi["Pulumi IaC"]:::infra
    GHActions["GitHub Actions"]:::infra
    PreMerge["run-before-merge.sh"]:::infra
    GHActions --> Pulumi
    PreMerge --> GHActions
    Pulumi --> Firebase
    Pulumi --> APIGW
    Pulumi --> Backend
    Pulumi --> POC
    Pulumi --> NewUI
  end

  %% Click Events
  click POC "https://github.com/tabiya-tech/compass/tree/main/frontend/"
  click NewUI "https://github.com/tabiya-tech/compass/tree/main/frontend-new/"
  click Backend "https://github.com/tabiya-tech/compass/blob/main/backend/app/server.py"
  click AD "https://github.com/tabiya-tech/compass/tree/main/backend/app/agent/agent_director/"
  click CEA "https://github.com/tabiya-tech/compass/tree/main/backend/app/agent/collect_experiences_agent/"
  click QNA "https://github.com/tabiya-tech/compass/blob/main/backend/app/agent/qna_agent.py"
  click SEA "https://github.com/tabiya-tech/compass/tree/main/backend/app/agent/skill_explorer_agent/"
  click WA "https://github.com/tabiya-tech/compass/blob/main/backend/app/agent/welcome_agent.py"
  click CMM "https://github.com/tabiya-tech/compass/blob/main/backend/app/conversation_memory/conversation_memory_manager.py"
  click Mongo "https://github.com/tabiya-tech/compass/blob/main/backend/app/store/database_application_state_store.py"
  click InMem "https://github.com/tabiya-tech/compass/blob/main/backend/app/store/in_memory_application_state_store.py"
  click JSONStore "https://github.com/tabiya-tech/compass/blob/main/backend/app/store/json_application_state_store.py"
  click TXTStore "https://github.com/tabiya-tech/compass/blob/main/backend/app/store/txt_application_state_store.py"
  click MDStore "https://github.com/tabiya-tech/compass/blob/main/backend/app/store/markdown_conversation_state_store.py"
  click ESCOEnt "https://github.com/tabiya-tech/compass/blob/main/backend/app/vector_search/esco_entities.py"
  click Emb "https://github.com/tabiya-tech/compass/blob/main/backend/app/vector_search/embeddings_model.py"
  click ESSvc "https://github.com/tabiya-tech/compass/blob/main/backend/app/vector_search/esco_search_service.py"
  click SSSvc "https://github.com/tabiya-tech/compass/blob/main/backend/app/vector_search/similarity_search_service.py"
  click OccRoutes "https://github.com/tabiya-tech/compass/blob/main/backend/app/vector_search/occupation_search_routes.py"
  click SkillRoutes "https://github.com/tabiya-tech/compass/blob/main/backend/app/vector_search/skill_search_routes.py"
  click FBRoutes "https://github.com/tabiya-tech/compass/blob/main/backend/app/conversations/feedback/routes/routes.py"
  click FBRepo "https://github.com/tabiya-tech/compass/blob/main/backend/app/conversations/feedback/repository/repository.py"
  click FBServ "https://github.com/tabiya-tech/compass/blob/main/backend/app/conversations/feedback/services/service.py"
  click InvRoutes "https://github.com/tabiya-tech/compass/blob/main/backend/app/invitations/routes.py"
  click InvRepo "https://github.com/tabiya-tech/compass/blob/main/backend/app/invitations/repository.py"
  click MSRoutes "https://github.com/tabiya-tech/compass/blob/main/backend/app/metrics/routes/routes.py"
  click MSRepo "https://github.com/tabiya-tech/compass/blob/main/backend/app/metrics/repository/repository.py"
  click MSRec "https://github.com/tabiya-tech/compass/blob/main/backend/app/metrics/application_state_metrics_recorder/recorder.py"
  click MSServ "https://github.com/tabiya-tech/compass/blob/main/backend/app/metrics/services/service.py"
  click SensFilter "https://github.com/tabiya-tech/compass/blob/main/backend/app/sensitive_filter/sensitive_filter.py"
  click DepInject "https://github.com/tabiya-tech/compass/tree/main/backend/app/server_dependencies/"
  click Config "https://github.com/tabiya-tech/compass/blob/main/backend/app/app_config.py"
  click GHActions "https://github.com/tabiya-tech/compass/tree/main/.github/workflows/"
  click PreMerge "https://github.com/tabiya-tech/compass/blob/main/run-before-merge.sh"
  click Pulumi "https://github.com/tabiya-tech/compass/tree/main/iac/"

  %% Styles
  classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
  classDef backend fill:#DFFFE0,stroke:#28A745,color:#28A745
  classDef datastore fill:#FFF4E5,stroke:#FF8C00,color:#FF8C00
  classDef external fill:#F0F0F0,stroke:#6C757D,color:#6C757D
  classDef infra fill:#EDEDED,stroke:#6C757D,color:#343A40
```
