# matanshine/automatiq_home_assignment architecture

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

- Interactive diagram: https://gitdiagram.com/matanshine/automatiq_home_assignment
- Repository: https://github.com/matanshine/automatiq_home_assignment

## Overview

##### Project Type and Purpose
- This is a full-stack AI assistant application (“CyFortis Training Assistant”) that provides a chat interface for employees and CISOs to query cybersecurity training status.
- Frontend: React (TypeScript) + Vite, offering a chat UI.
- Backend: FastAPI (Python) exposing a single `/chat` endpoint that handles authentication, invokes an LLM via OpenAI API, executes read-only database “tools,” and returns structured chat responses.
- Data store: SQLite (employees.db).
- Orchestration: Docker Compose (frontend + backend containers).

##### File Structure Analysis
- Top-level: `docker-compose.yml`, `.env.example`, `.gitignore`, plus `backend/`, `frontend/`, and `assignment/`.
- `backend/`: Dockerfile + Python package. Under `app/`:
- `main.py` (FastAPI app and router)
- `api/endpoints.py` (single POST `/chat`)
- `db/`: raw SQLite queries, verifiers, schemas
- `services/`
– `agent_tools/`: tool schemas
– `llm/`: client setup, configuration, formatters, queries, responses, tool handlers
– `cache/`: LLM result caching and CISO stats caching
- `frontend/`: Dockerfiles, ESLint, basic HTML, React/Vite sources:
- `src/api/client.ts` (typed chat client)
- `components/`: Chat UI, messages, input bar, sidebar, theme toggle
- `hooks/`, `context/` for session and theming
- `docker-compose.yml` starts two services, binds mounts, hot-reload.

##### Key README Insights
- Single `/chat` endpoint handles all chat interactions.
- Auth flow: LLM first prompts for ID + name, backend verifies against SQLite, sets `is_ciso` flag.
- Tooling: LLM is given a suite of read-only “tools” (e.g., get_employee_status, list_employees_by_status). LLM chooses tool, backend runs handler, and returns result.
- Caching: LLM response caching and expensive CISO stats caching.
- Stateless design: every request includes full history + auth, enabling horizontal scaling.
- No ORM, plain sqlite3 for transparency.

##### Main Components
A. User Interface (Browser)
- Components: ChatInput, ChatHistory, Theme Switch
- Connects via HTTP/WebSocket to the Frontend Dev Server (port 3000)
B. Frontend Container
- Vite dev server
- Code hot reload
- API client calls `/chat`
C. Backend Container
- FastAPI app (port 8000)
- Single `/chat` endpoint
- Auth verifier
- LLM orchestration service
- Tool registry and handlers
- Cache service
- SQLite database file mounted
D. External Service
- OpenAI API (LLM)
E. Database
- SQLite `employees.db`
F. Docker Compose
- Orchestrates Frontend and Backend containers
- Injects environment variables (OPENAI_API_KEY)

##### Relationships and Data Flows
1. User types message in browser → Frontend Dev Server (HTTP POST to `/chat`)
2. Frontend forwards request (includes chat history + optional auth fields) to FastAPI
3. Backend:
a. Verify auth (ID + name) against SQLite
b. Build system prompt + history + tool definitions
c. Call OpenAI API → receive LLM response or “tool call” request
d. If tool call: invoke local handler → run SQLite query → return structure to LLM
e. Possibly chain multiple tool calls via LLM
f. Final LLM completion → format ChatResponse
4. Backend returns JSON to Frontend
5. Frontend renders new chat message

##### Architectural Patterns and Principles
- Single-endpoint orchestration pattern: centralizes auth, tool chaining, formatting.
- Tool abstraction: clear separation between LLM logic (prompts) and business logic (DB queries).
- Stateless services: each `/chat` request self-contained.
- Containerization: each tier in its own Docker container, orchestrated via Docker Compose.
- Caching layer: decoupled caching service for DB results and LLM responses.

##### Technologies and Frameworks
- Frontend: React, TypeScript, Vite, CSS modules
- Backend: FastAPI, Pydantic (schemas), sqlite3, python-dotenv, OpenAI Python client
- Caching: in-memory Python caches (backend/services/cache)
- Orchestration: Docker, Docker Compose

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker Compose Orchestration
    subgraph "Docker Compose" 
        direction TB
        Frontend_Container["Frontend Container"]:::frontend_service
        Backend_Container["Backend Container"]:::backend_service
    end

    %% Browser UI Layer
    subgraph "Browser UI" 
        direction TB
        InputBar["Chat Input"]:::ui
        ChatHistory["Chat History"]:::ui
        ChatMessage["Chat Message Display"]:::ui
        Sidebar["Sidebar / Employee List"]:::ui
        ThemeToggle["Theme Toggle Switch"]:::ui
    end

    %% Frontend Service
    subgraph Frontend_Container
        direction TB
        ViteServer["Vite Dev Server (port 3000)"]:::frontend_service
        ApiClient["API Client"]:::frontend_service
    end

    %% Backend Service
    subgraph Backend_Container
        direction TB
        MainApp["FastAPI App (/chat)"]:::backend_service
        AuthVerifier["Auth Verifier"]:::backend_service
        ToolRegistry["Tool Registry"]:::backend_service
        LLMClient["LLM Client"]:::backend_service
        ToolHandlers["Tool Handlers"]:::backend_service
        CacheService["Cache Service"]:::backend_service
        DBAccess["DB Access"]:::backend_service
    end

    %% External and Database
    OpenAI["OpenAI API"]:::external
    SQLiteDB["SQLite employees.db"]:::database

    %% Flows
    InputBar -->|types message| ViteServer
    ChatHistory -->|renders history| ViteServer
    ChatMessage -->|renders message| ViteServer
    Sidebar -->|renders list| ViteServer
    ThemeToggle -->|toggles theme| ViteServer

    ViteServer -->|POST /chat| ApiClient
    ApiClient -->|POST /chat| MainApp

    MainApp -->|verify auth| AuthVerifier
    AuthVerifier -->|SQL SELECT| DBAccess
    MainApp -->|load tools| ToolRegistry
    MainApp -->|build prompt| LLMClient
    LLMClient -->|chat completion| OpenAI
    OpenAI -->|LLM response| LLMClient
    LLMClient -->|parse tool call| ToolHandlers
    ToolHandlers -->|SQL SELECT| DBAccess
    ToolHandlers -->|result| LLMClient
    LLMClient -->|formatted response| MainApp
    MainApp -->|cache results| CacheService
    MainApp -->|JSON response| ApiClient

    ApiClient -->|response| ViteServer
    ViteServer -->|render| ChatHistory
    ViteServer -->|render| ChatMessage

    %% Database connection
    DBAccess -->|reads/writes| SQLiteDB

    %% Click Events
    click InputBar "https://github.com/matanshine/automatiq_home_assignment/blob/main/frontend/src/components/InputBar.tsx"
    click ChatHistory "https://github.com/matanshine/automatiq_home_assignment/blob/main/frontend/src/components/Chat.tsx"
    click ChatMessage "https://github.com/matanshine/automatiq_home_assignment/blob/main/frontend/src/components/ChatMessage.tsx"
    click Sidebar "https://github.com/matanshine/automatiq_home_assignment/blob/main/frontend/src/components/Sidebar.tsx"
    click ThemeToggle "https://github.com/matanshine/automatiq_home_assignment/blob/main/frontend/src/components/ThemeToggle.tsx"
    click ApiClient "https://github.com/matanshine/automatiq_home_assignment/blob/main/frontend/src/api/client.ts"
    click ViteServer "https://github.com/matanshine/automatiq_home_assignment/blob/main/frontend/src/main.tsx"
    click ViteServer "https://github.com/matanshine/automatiq_home_assignment/blob/main/frontend/vite.config.ts"
    click MainApp "https://github.com/matanshine/automatiq_home_assignment/blob/main/backend/app/main.py"
    click AuthVerifier "https://github.com/matanshine/automatiq_home_assignment/blob/main/backend/app/db/verifiers.py"
    click DBAccess "https://github.com/matanshine/automatiq_home_assignment/blob/main/backend/app/db/queries.py"
    click DBAccess "https://github.com/matanshine/automatiq_home_assignment/blob/main/backend/app/db/ciso.py"
    click DBAccess "https://github.com/matanshine/automatiq_home_assignment/blob/main/backend/app/db/regular_employee.py"
    click ToolRegistry "https://github.com/matanshine/automatiq_home_assignment/blob/main/backend/app/services/agent_tools/tools.py"
    click LLMClient "https://github.com/matanshine/automatiq_home_assignment/blob/main/backend/app/services/llm/llm_client_setup.py"
    click LLMClient "https://github.com/matanshine/automatiq_home_assignment/blob/main/backend/app/services/llm/llm_config.py"
    click LLMClient "https://github.com/matanshine/automatiq_home_assignment/blob/main/backend/app/services/llm/llm_client.py"
    click LLMClient "https://github.com/matanshine/automatiq_home_assignment/blob/main/backend/app/services/llm/llm_queries.py"
    click LLMClient "https://github.com/matanshine/automatiq_home_assignment/blob/main/backend/app/services/llm/llm_responses.py"
    click LLMClient "https://github.com/matanshine/automatiq_home_assignment/blob/main/backend/app/services/llm/llm_formatters.py"
    click ToolHandlers "https://github.com/matanshine/automatiq_home_assignment/blob/main/backend/app/services/llm/llm_tool_handlers.py"
    click CacheService "https://github.com/matanshine/automatiq_home_assignment/blob/main/backend/app/services/cache/llm_cache.py"
    click CacheService "https://github.com/matanshine/automatiq_home_assignment/blob/main/backend/app/services/cache/db_cache.py"
    click SQLiteDB "https://github.com/matanshine/automatiq_home_assignment/blob/main/backend/data/employees.db"
    click Frontend_Container "https://github.com/matanshine/automatiq_home_assignment/blob/main/frontend/Dockerfile.dev"
    click Frontend_Container "https://github.com/matanshine/automatiq_home_assignment/tree/main/frontend/Dockerfile"
    click Backend_Container "https://github.com/matanshine/automatiq_home_assignment/tree/main/backend/Dockerfile"
    click Frontend_Container "https://github.com/matanshine/automatiq_home_assignment/blob/main/docker-compose.yml"
    click Backend_Container "https://github.com/matanshine/automatiq_home_assignment/blob/main/docker-compose.yml"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#3399ff,color:#000
    classDef frontend_service fill:#d4edda,stroke:#28a745,color:#000
    classDef backend_service fill:#ffe5b4,stroke:#ff8c00,color:#000
    classDef database fill:#f5e6ca,stroke:#a67c00,color:#000
    classDef external fill:#e2d5f9,stroke:#6f42c1,color:#000
    classDef orchestration fill:#f0f0f0,stroke:#666666,color:#000,stroke-dasharray: 5 5
```
