How matanshine/automatiq_home_assignment works
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