# afinch21/somerville architecture

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

- Interactive diagram: https://gitdiagram.com/afinch21/somerville
- Repository: https://github.com/afinch21/somerville

## Overview

##### Main Components

a) Frontend Layer:
- NiceGUI-based frontend application
- Connection to FastAPI backend through HTTP requests
- Main UI components mentioned (Plan, Extract, Operations, and Evaluation tabs)

b) Backend Layer:
- FastAPI server
- API endpoints (/get_question_list, /answer_question, /get_evaluation)
- Core business logic components

c) Agent Layer:
- Two LLM agents
- OpenAI API integration
- Agent workflow orchestration

d) Data Layer:
- PostgreSQL database (optional)
- JSON file storage (alternative)
- Data models and ORM

##### Component Organization

**[Frontend Layer (NiceGUI)] ↔ [Backend Layer (FastAPI)] ↔ [Agent Layer] ↔ [Data Layer]**

Frontend Layer:
**[UI Components]**
- Plan View
- Extract View
- Operations View
- Evaluation View

Backend Layer:
**[FastAPI Server]**
- API Endpoints
- Model Definitions
- Utility Services
- AppStartup
- PromptTemplates
- ProcessEvalResults

Agent Layer:
**[Agent System]**
- Agent Archetypes
- Agent Workflow
- Operation Executor
- OpenAI API Integration

Data Layer:
**[Storage]**
- PostgreSQL Database
- ORM Models
- JSON File Storage
- ConvFincQA_data.json
- agents.json
- prompts.json

##### Important Flows to Highlight

a) Question Processing Flow:
**UI → API → Agent Workflow → LLM Processing → Data Storage → Response**

b) Evaluation Flow:
**Request → Data Retrieval → Agent Processing → Result Comparison → Evaluation Summary**

##### Technical Details

- Port configurations (80 for API)
- Database connection string format
- File storage paths
- API endpoint specifications
- Environment variable dependencies

##### Recommendations

- Version information for major components
- Notes about scalability points
- Document error handling paths
- Configuration dependencies

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and Classes
    classDef frontend fill:#4A90E2,stroke:#2E5B99,color:white
    classDef backend fill:#50C878,stroke:#2E8B57,color:white
    classDef agent fill:#9370DB,stroke:#483D8B,color:white
    classDef data fill:#FFD700,stroke:#DAA520,color:black
    classDef logger fill:#FF6B6B,stroke:#CD5C5C,color:white
    classDef test fill:#A9A9A9,stroke:#696969,color:white
    classDef api fill:#87CEEB,stroke:#4682B4,color:white

    %% Frontend Layer
    subgraph Frontend
        UI["Main UI Application"]
        APIComm["API Communication"]
        FrontFuncs["Frontend Functions"]
        UI --> APIComm
        UI --> FrontFuncs
    end

    %% Backend Layer
    subgraph Backend
        FastAPI["FastAPI Server"]
        CoreModel["Core Model"]
        AppConfig["App Configuration"]
        PromptMgmt["Prompt Management"]
        EvalProc["Evaluation Processing"]
        FastAPI --> CoreModel
        FastAPI --> AppConfig
        FastAPI --> PromptMgmt
        FastAPI --> EvalProc
    end

    %% Agent Layer
    subgraph Agents
        AgentDef["Agent Definitions"]
        AgentSub["Agent Subtypes"]
        AgentInit["Agent Initialization"]
        AgentWork["Agent Workflow"]
        OpExec["Operation Execution"]
        TokenMgmt["Token Management"]
        AgentDef --> AgentSub
        AgentInit --> AgentWork
        AgentWork --> OpExec
        OpExec --> TokenMgmt
    end

    %% Data Layer
    subgraph Data
        DB["Database Core"]
        ORM["ORM Models"]
        DBOps["Database Operations"]
        JSON["JSON Storage"]
        DB --> ORM
        DB --> DBOps
        DB -.-> JSON
    end

    %% Logger
    Logger["Logger System"]

    %% Testing
    subgraph Testing
        AgentTest["Agent Testing"]
        DBTest["Database Testing"]
        OpsTest["Operations Testing"]
        EvalTest["Evaluation Testing"]
        PromptTest["Prompt Testing"]
    end

    %% Connections between layers
    Frontend --> FastAPI
    FastAPI --> Agents
    Agents --> Data
    Logger --> Frontend
    Logger --> Backend
    Logger --> Agents
    Logger --> Data

    %% Click events for component mapping
    click UI "https://github.com/AFinch21/Somerville/blob/main/src/frontend/main.py"
    click APIComm "https://github.com/AFinch21/Somerville/blob/main/src/frontend/APICalls.py"
    click FrontFuncs "https://github.com/AFinch21/Somerville/blob/main/src/frontend/FrontendFucntions.py"
    click FastAPI "https://github.com/AFinch21/Somerville/blob/main/src/main.py"
    click CoreModel "https://github.com/AFinch21/Somerville/blob/main/src/model/Model.py"
    click AppConfig "https://github.com/AFinch21/Somerville/blob/main/src/utilities/AppStartup.py"
    click PromptMgmt "https://github.com/AFinch21/Somerville/blob/main/src/utilities/PromptTemplates.py"
    click EvalProc "https://github.com/AFinch21/Somerville/blob/main/src/utilities/ProcessEvalResults.py"
    click AgentDef "https://github.com/AFinch21/Somerville/blob/main/src/agents/AgentArchetype.py"
    click AgentSub "https://github.com/AFinch21/Somerville/blob/main/src/agents/AgentSubtype.py"
    click AgentInit "https://github.com/AFinch21/Somerville/blob/main/src/agents/AgentInitialisation.py"
    click AgentWork "https://github.com/AFinch21/Somerville/blob/main/src/utilities/AgentWorkflow.py"
    click OpExec "https://github.com/AFinch21/Somerville/blob/main/src/utilities/OperationExecutor.py"
    click TokenMgmt "https://github.com/AFinch21/Somerville/blob/main/src/utilities/TokenCounter.py"
    click DB "https://github.com/AFinch21/Somerville/blob/main/src/database/Database.py"
    click ORM "https://github.com/AFinch21/Somerville/blob/main/src/database/ORM.py"
    click DBOps "https://github.com/AFinch21/Somerville/blob/main/src/database/Operations.py"
    click JSON "https://github.com/AFinch21/Somerville/tree/main/src/data"
    click Logger "https://github.com/AFinch21/Somerville/blob/main/src/logger/Logger.py"
    click AgentTest "https://github.com/AFinch21/Somerville/blob/main/src/tests/test_agent_workflow.py"
    click DBTest "https://github.com/AFinch21/Somerville/blob/main/src/tests/test_database_operations.py"
    click OpsTest "https://github.com/AFinch21/Somerville/blob/main/src/tests/test_operation_executor.py"
    click EvalTest "https://github.com/AFinch21/Somerville/blob/main/src/tests/test_processing_evals.py"
    click PromptTest "https://github.com/AFinch21/Somerville/blob/main/src/tests/test_prompt_building.py"

    %% Style applications
    class UI,APIComm,FrontFuncs frontend
    class FastAPI,CoreModel,AppConfig,PromptMgmt,EvalProc backend
    class AgentDef,AgentSub,AgentInit,AgentWork,OpExec,TokenMgmt agent
    class DB,ORM,DBOps,JSON data
    class Logger logger
    class AgentTest,DBTest,OpsTest,EvalTest,PromptTest test
```
