# cgoncalves94/multi-agent-pydanticai architecture

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

- Interactive diagram: https://gitdiagram.com/cgoncalves94/multi-agent-pydanticai
- Repository: https://github.com/cgoncalves94/multi-agent-pydanticai

## Overview

##### Project Type and Purpose
- This is a full-stack, multi-agent AI chat application.
- Frontend: Next.js + TypeScript + Material UI for the interactive chat UI.
- Backend: FastAPI + Pydantic + SQLite providing HTTP endpoints, orchestrating AI “agents,” and persisting chat sessions.

##### Top-Level Components
a. Frontend (frontend/)
- Next.js App (app/, page.tsx, layout.tsx)
- React Components for chat UI: ChatHeader, ChatInput, ChatMessages, CodeBlock, ImageAnalysis, SearchResults, ModeToggle
- ThemeRegistry + global CSS + Material UI theme
- apiService.ts for REST API calls
b. Backend (backend/)
- FastAPI app (app.py)
- Agent orchestrator (agents.py) implementing Code Expert, Search Expert, Image Expert
- Database module (database.py) using SQLite to store sessions and messages
- Pydantic models for request/response validation
c. Database
- SQLite file managed by SQLModel/Pydantic
d. External AI & Tools
- OpenAI GPT-4o / Google Gemini via REST API keys
- Web search API (for Search Expert)
- Image analysis API or Vision models
e. Dev & Ops
- Uvicorn runner, .env configuration, Makefile targets for dev, linting, pre-commit

##### Relationships and Data Flow
- Browser → Next.js frontend UI
- User inputs → React chat components → apiService
- Frontend → Backend
- HTTP(S) requests (REST endpoints exposed by FastAPI)
- Streaming vs structured JSON responses
- Backend Orchestration
- Receives user message → routes to appropriate Agent(s)
- Code Expert calls OpenAI/Gemini for code generation/execution
- Search Expert triggers web search, summarizes results
- Image Expert sends uploaded images for object detection
- Backend → Database
- Persist chat history, session IDs, agent responses
- Backend → External Services
- REST calls to AI providers and web search
- Backend → Frontend
- Streams back responses or full JSON payloads

##### Architectural Patterns & Principles
- Layered Separation:
- Presentation (Next.js React)
- Application/API (FastAPI endpoints)
- Domain Logic (Agent orchestrator)
- Data (SQLite via Pydantic/SQLModel)
- Single-Process Micro-service Style:
- Agents are modules, not separate deployables, but can be refactored into microservices if needed
- Streaming Data Flow:
- Use HTTP chunked responses for streaming agent replies
- API‐First Design:
- Clear Pydantic schemas for request/response

- Notes on extension points: how to add a new Agent module or swap the DB.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User"]:::external

    %% Subgraph Frontend
    subgraph "Frontend (Next.js + React)" 
        direction TB
        PagePage["page.tsx"]:::frontend
        PageLayout["layout.tsx"]:::frontend
        GlobalsCSS["globals.css"]:::frontend
        ThemeRegistry["ThemeRegistry"]:::frontend
        MaterialTheme["theme.ts"]:::frontend
        ChatHeader["ChatHeader"]:::frontend
        ChatInput["ChatInput"]:::frontend
        ChatMessages["ChatMessages / ChatMessage"]:::frontend
        CodeBlock["CodeBlock"]:::frontend
        ImageAnalysis["ImageAnalysis"]:::frontend
        SearchResults["SearchResults"]:::frontend
        ModeToggle["ModeToggle"]:::frontend
        APIService["apiService.ts"]:::frontend
        APIConfig["api.ts"]:::frontend
        APITypes["apiServiceTypes.ts / chatTypes.ts"]:::frontend
        ChatLayout["ChatLayout.tsx"]:::frontend
        WelcomePage["WelcomePage.tsx"]:::frontend
    end

    %% Subgraph Backend
    subgraph "Backend (FastAPI + Agents)" 
        direction TB
        FastAPIApp["app.py"]:::backend
        Agents["agents.py (Code/Search/Image Expert)"]:::backend
        DatabaseModule["database.py"]:::db
        EnvExample[".env.example"]:::backend
        Makefile["Makefile"]:::backend
        PreCommit[".pre-commit-config.yaml"]:::backend
        CIWorkflow[".github/workflows/pre_commit_hooks.yaml"]:::backend
    end

    %% External Services
    subgraph "External AI & Tools"
        direction TB
        OpenAI["OpenAI GPT-4o / Gemini"]:::external
        WebSearch["Web Search API"]:::external
        VisionAPI["Image Analysis API"]:::external
    end

    %% Database
    Database["SQLite DB"]:::db

    %% Connections
    User -->|inputs| ChatInput
    ChatInput -->|"calls apiService"| APIService
    APIService -->|"HTTP REST (stream/JSON)"| FastAPIApp
    FastAPIApp -->|"routes request"| Agents
    Agents -->|"persist session"| DatabaseModule
    DatabaseModule -->|writes| Database
    Agents -->|"calls OpenAI/Gemini"| OpenAI
    Agents -->|"calls Web Search"| WebSearch
    Agents -->|"calls Image Analysis"| VisionAPI
    Agents -->|"returns response"| FastAPIApp
    FastAPIApp -->|"streams/JSON response"| APIService
    APIService -->|"updates UI"| ChatMessages
    Makefile -->|orchestrates dev| FastAPIApp
    Makefile -->|orchestrates dev| PagePage

    %% Click events
    click PagePage "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/frontend/src/app/page.tsx"
    click PageLayout "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/frontend/src/app/layout.tsx"
    click GlobalsCSS "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/frontend/src/app/globals.css"
    click ThemeRegistry "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/frontend/src/components/ThemeRegistry.tsx"
    click MaterialTheme "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/frontend/src/theme.ts"
    click ChatHeader "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/frontend/src/components/chat/ChatHeader.tsx"
    click ChatInput "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/frontend/src/components/chat/ChatInput.tsx"
    click ChatMessages "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/frontend/src/components/chat/ChatMessages.tsx"
    click CodeBlock "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/frontend/src/components/chat/CodeBlock.tsx"
    click ImageAnalysis "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/frontend/src/components/chat/ImageAnalysis.tsx"
    click SearchResults "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/frontend/src/components/chat/SearchResults.tsx"
    click ModeToggle "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/frontend/src/components/chat/ModeToggle.tsx"
    click ChatLayout "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/frontend/src/components/layouts/ChatLayout.tsx"
    click WelcomePage "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/frontend/src/components/layouts/WelcomePage.tsx"
    click APIService "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/frontend/src/services/apiService.ts"
    click APIConfig "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/frontend/src/config/api.ts"
    click APITypes "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/frontend/src/types/apiServiceTypes.ts"
    click FastAPIApp "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/backend/src/app.py"
    click Agents "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/backend/src/agents.py"
    click DatabaseModule "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/backend/src/database.py"
    click EnvExample "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/backend/.env.example"
    click Makefile "https://github.com/cgoncalves94/multi-agent-pydanticai/tree/master/Makefile"
    click PreCommit "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/.pre-commit-config.yaml"
    click CIWorkflow "https://github.com/cgoncalves94/multi-agent-pydanticai/blob/master/.github/workflows/pre_commit_hooks.yaml"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#006064
    classDef backend fill:#e8f5e9,stroke:#1b5e20,color:#1b5e20
    classDef db fill:#fff3e0,stroke:#ef6c00,color:#e65100
    classDef external fill:#eeeeee,stroke:#616161,color:#424242
```
