# yashksaini-coder/hack-agent-server architecture

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

- Interactive diagram: https://gitdiagram.com/yashksaini-coder/hack-agent-server
- Repository: https://github.com/yashksaini-coder/hack-agent-server

## Overview

##### Project type and purpose
- This is a monolithic, full‑stack web application whose backend is a REST API server built with FastAPI.
- It also serves server‑rendered pages (via Jinja2 templates) and static assets under “public.”
- It integrates with an external AI library (Agno) and likely caches or brokers data through Redis.

##### File structure
- Top level:
- app.py – entrypoint that instantiates FastAPI, mounts routers, templates, static files.
- Dockerfile + docker‑compose.yaml – containerization (app + Redis).
- requirements.txt – Python dependencies.
- .env.example – configuration variables (e.g., Redis URL, Render deploy settings).
- controllers/ – business logic for each feature (agent, chat, stock analysis, news, top stocks).
- routes/ – HTTP routing layer that delegates to controllers.
- templates/ – Jinja2 templates for server‑rendered HTML pages.
- public/ – static assets (images, CSS, JS).
- scripts/ – support scripts (health check ping).

##### Key insights from README
- FastAPI framework serves both REST endpoints and Jinja2 templates.
- Agno library is invoked within controllers to obtain AI predictions.
- Deployed via Docker Compose (app + Redis).
- Hosted on Render (single‑port service).

##### Main components & their relationships
a. Client (Browser or API consumer)
b. FastAPI App (Docker container)
- Route Layer (routes/*.py)
- Controller Layer (controllers/*.py)
- Template Engine (templates/) & Static Server (public/)
c. Redis (cache / message broker)
d. External AI Service (Agno)
e. External Stock Data Providers (third‑party APIs)
f. GitHub Actions (ping workflow) – optional, for uptime checks

- Flow example:
1. Client → HTTP GET/POST → Route (/stock, /chat, /agent, etc.)
2. Route → invokes appropriate Controller
3. Controller → checks Redis cache → if miss, fetch stock data from external API
4. Controller → calls Agno AI library for predictions
5. Controller → writes/reads Redis as needed
6. Controller → returns JSON or renders HTML via Jinja2 templates
7. FastAPI → HTTP response → Client

##### Architectural patterns & design principles
- Layered MVC‑like separation: Routes (Controller interface) → Controllers (Business logic) → External Services
- Single‑process monolith wrapped in containers
- Use of caching layer (Redis) to improve performance
- External AI integration decoupled via library calls (Agno)
- Container orchestration via Docker Compose

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client (Browser/API)"]:::client

    %% Docker Compose Containers
    subgraph "Docker Compose"
        direction TB
        AppContainer["FastAPI App Container"]:::container
        RedisContainer["Redis Container"]:::container
    end

    %% FastAPI App internal structure
    subgraph "FastAPI App"
        direction TB
        %% Route Layer
        subgraph "Route Layer"
            direction TB
            AgentRoutes["agentRoutes.py"]:::internal
            StockRoutes["stockRoutes.py"]:::internal
        end

        %% Controller Layer
        subgraph "Controller Layer"
            direction TB
            AgentController["agent.py"]:::internal
            ChatController["chat.py"]:::internal
            StockAgentController["stockAgent.py"]:::internal
            StockNewsController["stockNews.py"]:::internal
            TopStocksController["topStocks.py"]:::internal
        end

        %% Templating & Static
        Templates["Jinja2 Templates"]:::internal
        StaticAssets["Static Assets"]:::internal
    end

    %% External Services
    Agno["Agno AI Library"]:::external
    StockAPI["External Stock Data API"]:::external

    %% CI/Monitoring
    PingScript["scripts/ping.js"]:::external
    PingWorkflow[".github/workflows/ping.yml"]:::external

    %% Configuration & Build
    subgraph "Configuration & Build"
        direction TB
        Dockerfile["Dockerfile"]:::config
        ComposeFile["docker-compose.yaml"]:::config
        EnvExample[".env.example"]:::config
        Requirements["requirements.txt"]:::config
    end

    %% Connections
    Client -->|"HTTP Request"| AgentRoutes
    Client -->|"HTTP Request"| StockRoutes
    AgentRoutes -->|"calls"| AgentController
    StockRoutes -->|"calls"| StockAgentController
    AgentRoutes -->|"calls"| ChatController
    StockRoutes -->|"calls"| StockNewsController
    StockRoutes -->|"calls"| TopStocksController

    AgentController -->|"Cache Read/Write"| RedisContainer
    ChatController -->|"Cache Read/Write"| RedisContainer
    StockAgentController -->|"Fetch Data"| StockAPI
    StockNewsController -->|"Fetch Data"| StockAPI
    TopStocksController -->|"Fetch Data"| StockAPI

    AgentController -->|"AI Prediction"| Agno
    ChatController -->|"AI Prediction"| Agno
    StockAgentController -->|"AI Prediction"| Agno

    ControllerLayerEndpoints((Controllers)) --> Templates
    ControllerLayerEndpoints --> StaticAssets
    Templates -->|"Render HTML"| Client
    StaticAssets -->|"Serve Static"| Client

    AppContainer -->|"uses"| RedisContainer
    AppContainer -->|"configured by"| Dockerfile
    AppContainer -->|"configured by"| ComposeFile
    AppContainer -->|"uses"| EnvExample
    AppContainer -->|"depends on"| Requirements

    PingScript -->|"/ping"| AppContainer
    PingWorkflow -->|triggers| PingScript

    %% Click events
    click AppContainer "https://github.com/yashksaini-coder/hack-agent-server/blob/v2/app.py"
    click ComposeFile "https://github.com/yashksaini-coder/hack-agent-server/blob/v2/docker-compose.yaml"
    click Dockerfile "https://github.com/yashksaini-coder/hack-agent-server/tree/v2/Dockerfile"
    click AgentRoutes "https://github.com/yashksaini-coder/hack-agent-server/blob/v2/routes/agentRoutes.py"
    click StockRoutes "https://github.com/yashksaini-coder/hack-agent-server/blob/v2/routes/stockRoutes.py"
    click AgentController "https://github.com/yashksaini-coder/hack-agent-server/blob/v2/controllers/agent.py"
    click ChatController "https://github.com/yashksaini-coder/hack-agent-server/blob/v2/controllers/chat.py"
    click StockAgentController "https://github.com/yashksaini-coder/hack-agent-server/blob/v2/controllers/stockAgent.py"
    click StockNewsController "https://github.com/yashksaini-coder/hack-agent-server/blob/v2/controllers/stockNews.py"
    click TopStocksController "https://github.com/yashksaini-coder/hack-agent-server/blob/v2/controllers/topStocks.py"
    click Templates "https://github.com/yashksaini-coder/hack-agent-server/tree/v2/templates/"
    click StaticAssets "https://github.com/yashksaini-coder/hack-agent-server/tree/v2/public/"
    click RedisContainer "https://github.com/yashksaini-coder/hack-agent-server/blob/v2/docker-compose.yaml"
    click EnvExample "https://github.com/yashksaini-coder/hack-agent-server/blob/v2/.env.example"
    click Requirements "https://github.com/yashksaini-coder/hack-agent-server/blob/v2/requirements.txt"
    click PingScript "https://github.com/yashksaini-coder/hack-agent-server/blob/v2/scripts/ping.js"
    click PingWorkflow "https://github.com/yashksaini-coder/hack-agent-server/blob/v2/.github/workflows/ping.yml"

    %% Styles
    classDef client fill:#cccccc,stroke:#333,stroke-width:1px
    classDef container fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef internal fill:#90ee90,stroke:#333,stroke-width:1px
    classDef external fill:#FFD700,stroke:#333,stroke-width:1px
    classDef config fill:#f0e68c,stroke:#333,stroke-width:1px
```
