# neural-maze/philoagents-course architecture

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

- Interactive diagram: https://gitdiagram.com/neural-maze/philoagents-course
- Repository: https://github.com/neural-maze/philoagents-course

## Overview

##### Project Type and Purpose
- This is a full-stack AI-powered game simulation engine (“PhiloAgents”) that impersonates historical philosophers via dynamic conversation agents.
- Two distinct applications:
- philoagents-api (Python/FastAPI backend with agent orchestration, RAG, memory, evaluation)
- philoagents-ui (Node.js/Phaser-powered frontend with HTTP + WebSocket client)

##### High-Level Architecture Overview
- Frontend UI container
- Backend API container
- Data stores (MongoDB for long-term memory, vector DB for RAG)
- External AI services (GroqCloud + optionally OpenAI)
- Data ingestion pipelines (Wikipedia + Stanford Encyclopedia)
- Evaluation & monitoring components

##### Main Components
a. Frontend Layer (“philoagents-ui”)
– Browser Game (Phaser)
– ApiService (HTTP/REST)
– WebSocketApiService (real-time chat)
b. Backend Layer (“philoagents-api”)
1. API Gateway (FastAPI + Uvicorn)
- REST endpoints (/generate_response, /reset_conversation)
- WebSocket endpoint for live dialogue
2. Application Services
- ConversationService (orchestrates workflow graph of nodes/edges/chains)
- DataService (document extraction, deduplication)
- RAGService (embeddings, retriever, splitter)
- MemoryService
– Short-term (in-memory per session)
– Long-term (MongoDB collections, `philoagents.infrastructure.mongo.client`)
- EvaluationService (dataset generation, agent evaluation)
3. Domain Layer
- Philosopher entities, prompts, evaluation rules, exception models
4. Infrastructure Layer
- MongoDB adapter
- Opik utilities (vector store integration)
- LangGraph/LangChain connectors to LLMs
c. Data Stores
– MongoDB (long-term memory, prompt history, evaluation metadata)
– Vector database (via Opik or external vector store)
d. External Services
– LLM inference (GroqCloud API, optional OpenAI)
– Data sources (Wikipedia + Stanford Encyclopedia; ingested at runtime)
e. DevOps & Tooling
– Docker Compose orchestrates API, UI, MongoDB
– Makefiles & pyproject.toml & package.json for builds
– CI/Monitoring hooks for LLMOps (prompt versioning, evaluation jobs)

##### Relationships & Data Flows
- User clicks in UI → ApiService → FastAPI controller
- Controller invokes ConversationService →
- Retrieves context from Short-term memory
- Calls RAGService to fetch relevant docs via vector DB
- Calls LLM via LangGraph connector (Groq/OpenAI)
- Updates memory stores (in-memory & MongoDB)
- ConversationService returns response → WebSocket/HTTP → UI
- EvaluationService runs asynchronously (calls LLM judge, stores results)
- Data ingestion jobs (create_long_term_memory.py) fetch external data → vector DB & MongoDB

##### Architectural Patterns & Principles
- Hexagonal (ports & adapters): separates Domain, Application, Infrastructure
- Layered modular monolith (clear boundaries between services)
- RAG pipeline as a sub-system (splitter → embeddings → retriever → LLM chain)
- Event/workflow graph for conversation orchestration (nodes & edges model)
- LLMOps best practices: versioned prompts, automated evaluation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker Compose Boundary
    subgraph "Docker Compose" 
        direction TB
        %% UI Container
        subgraph "UI (philoagents-ui)" 
            direction TB
            Game["Browser Game (Phaser)"]:::frontend
            ApiService["ApiService (HTTP/REST)"]:::frontend
            WebSocketApiService["WebSocketApiService (WebSocket)"]:::frontend
        end

        %% API Container
        subgraph "API (philoagents-api)"
            direction TB
            APIGateway["API Gateway (FastAPI/Uvicorn)"]:::backend
            subgraph "Application Services"
                direction TB
                ConversationService["ConversationService"]:::backend
                DataService["DataService"]:::backend
                RAGService["RAGService"]:::backend
                MemoryService["MemoryService"]:::backend
                EvaluationService["EvaluationService"]:::backend
            end
            subgraph "Domain & Infrastructure"
                direction TB
                DomainLayer["Domain Layer"]:::backend
                InfraLayer["Infrastructure Layer"]:::backend
            end
        end

        MongoDB["MongoDB"]:::datastore
    end

    %% External & Infra
    VectorDB["Vector DB"]:::datastore
    GroqCloud["GroqCloud / OpenAI"]:::external
    DataSources["Wikipedia / Stanford Encyclopedia"]:::external
    DataIngestion["Data Ingestion Tools"]:::backend

    %% Flows
    Game -->|HTTP| ApiService
    Game -->|WebSocket| WebSocketApiService
    ApiService -->|REST| APIGateway
    WebSocketApiService -->|WS| APIGateway

    APIGateway -->|"invoke"| ConversationService
    APIGateway -->|"invoke"| DataService
    APIGateway -->|"invoke"| EvaluationService

    ConversationService -->|"short-term memory"| MemoryService
    ConversationService -->|"RAG lookup"| RAGService
    ConversationService -->|"LLM call"| InfraLayer
    ConversationService -->|"update memory"| MemoryService

    MemoryService -->|"long-term persist"| MongoDB
    DataService -->|"store docs"| MongoDB
    RAGService -->|"embeddings & retrieve"| VectorDB
    EvaluationService -->|"store eval results"| MongoDB

    DataIngestion -->|"ingest data"| DataSources
    DataIngestion -->|"load"| MongoDB
    DataIngestion -->|"load"| VectorDB

    ConversationService -->|uses| DomainLayer

    InfraLayer -->|Mongo adapter| MongoDB
    InfraLayer -->|vector utils| VectorDB
    InfraLayer -->|LangGraph connector| GroqCloud

    %% Click Events
    click Game "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-ui/src/scenes/Game.js"
    click ApiService "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-ui/src/services/ApiService.js"
    click WebSocketApiService "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-ui/src/services/WebSocketApiService.js"
    click APIGateway "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/src/philoagents/infrastructure/api.py"
    click ConversationService "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/src/philoagents/application/conversation_service/generate_response.py"
    click ConversationService "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/src/philoagents/application/conversation_service/reset_conversation.py"
    click ConversationService "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/src/philoagents/application/conversation_service/workflow/graph.py"
    click DataService "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/src/philoagents/application/data/extract.py"
    click DataService "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/src/philoagents/application/data/deduplicate_documents.py"
    click RAGService "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/src/philoagents/application/rag/splitters.py"
    click RAGService "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/src/philoagents/application/rag/embeddings.py"
    click RAGService "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/src/philoagents/application/rag/retrievers.py"
    click MemoryService "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/src/philoagents/application/long_term_memory.py"
    click MemoryService "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/src/philoagents/infrastructure/mongo/client.py"
    click MemoryService "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/src/philoagents/infrastructure/mongo/indexes.py"
    click EvaluationService "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/src/philoagents/application/evaluation/evaluate.py"
    click EvaluationService "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/src/philoagents/application/evaluation/generate_dataset.py"
    click EvaluationService "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/src/philoagents/application/evaluation/upload_dataset.py"
    click DomainLayer "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/src/philoagents/domain/philosopher.py"
    click InfraLayer "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/src/philoagents/infrastructure/opik_utils.py"
    click DataIngestion "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/tools/create_long_term_memory.py"
    click DataIngestion "https://github.com/neural-maze/philoagents-course/blob/main/philoagents-api/tools/delete_long_term_memory.py"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef datastore fill:#FFFF99,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
