# yashksaini-coder/investo-server architecture

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

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

## Overview

##### Main Components
- API Server Core (app.py): Represents the FastAPI entry point.
- Routing Layer: The files in the “routes” directory (agentRoutes.py & stockRoutes.py) define the various API endpoints.
- Controllers: The “controllers” folder houses multiple modules (agents.py, ask.py, stockAgent.py, stockNews.py, topStocks.py) that contain the business logic for handling specific tasks (e.g., interfacing with Agno AI for predictions, handling stock news, and managing stock agent functionalities).
- Utility Services: “utils/redisCache.py” handles interactions with Redis for caching purposes.
- Templates: The “templates” directory suggests some HTML templating is available, which may be used for rendering responses or for a lightweight client-side component.
- External Services:
- Agno AI is integrated into the backend for making predictions.
- Redis is used as a caching mechanism.
- The deployment target is Render, meaning the deployment and runtime environment is cloud-hosted.
- Docker (with its Dockerfile and docker-compose.yml) encapsulates the application environment.

##### Components Relationships & Interactions
- Clients (or the frontend) send HTTP requests to the FastAPI server.
- The FastAPI server (app.py) routes these requests through the defined routes (agentRoutes.py & stockRoutes.py).
- The routes then delegate to the appropriate controller modules housed in the “controllers” directory where the business logic is executed.
- When necessary, controllers interact with external services:
- They use the Agno AI library to process predictions.
- They may call functions from the “utils/redisCache.py” to query or update the Redis cache for improved performance.
- The server may render HTML responses using templates if needed.
- Docker ensures containerization of the project and docker-compose facilitates managing multi-container environments (if, for instance, separate containers are defined for FastAPI and Redis).

##### Design Principles & Architectural Patterns
- Layered Architecture: The clear separation between routing, controllers (business logic), and utilities (caching).
- REST API design: The project follows REST principles for handling HTTP requests.
- Separation of Concerns: Distinct folders for routes vs. controllers help maintain a clean architecture.
- Containerization and CI/CD: Docker and GitHub workflows (the ping.yml file in .github/workflows) are used to automate testing/health-checks and simplify deployment on Render.

##### Final Advice
- Avoid oversimplifying; the key is to break down the project into as many distinct components as possible to clearly represent its structure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client/Frontend"]:::client
    API["FastAPI Entry (app.py)"]:::backend

    Client -->|"HTTP_Request"| API

    subgraph "Routing Layer"
        AR["agentRoutes.py"]:::route
        SR["stockRoutes.py"]:::route
    end

    API -->|"routes"| AR
    API -->|"routes"| SR

    subgraph "Controllers Layer"
        A["agents.py"]:::controller
        ASK["ask.py"]:::controller
        SA["stockAgent.py"]:::controller
        SN["stockNews.py"]:::controller
        TS["topStocks.py"]:::controller
    end

    AR -->|"delegates"| A
    AR -->|"delegates"| ASK
    SR -->|"delegates"| SA
    SR -->|"delegates"| SN
    SR -->|"delegates"| TS

    subgraph "Utility Services"
        RC["Redis Cache (redisCache.py)"]:::utility
    end

    A -->|"uses"| RC
    ASK -->|"uses"| RC
    SA -->|"uses"| RC
    SN -->|"uses"| RC
    TS -->|"uses"| RC

    RC -->|"stores_retrieves"| RS["Redis Service"]:::external

    subgraph "Templates"
        T1["base.html"]:::template
        T2["route.html"]:::template
    end

    API -->|"renders"| T1
    API -->|"renders"| T2

    C_AI["Agno AI Service"]:::external
    A -->|"predicts_via"| C_AI
    ASK -->|"predicts_via"| C_AI
    SA -->|"predicts_via"| C_AI
    SN -->|"predicts_via"| C_AI
    TS -->|"predicts_via"| C_AI

    subgraph "Deployment"
        D1["Dockerfile"]:::container
        D2["docker-compose.yml"]:::container
        D3[".dockerignore"]:::container
        CICD["CI/CD Pipeline (ping.yml)"]:::cicd
        Render["Render (Cloud Deployment)"]:::external
    end

    CICD -->|"triggers"| D1
    CICD -->|"triggers"| D2
    CICD -->|"triggers"| D3
    D1 -->|"containers"| API
    D2 -->|"containers"| API
    D3 -->|"containers"| API
    D1 -->|"deploys_to"| Render
    D2 -->|"deploys_to"| Render
    D3 -->|"deploys_to"| Render

    classDef client fill:#FAD,stroke:#333,stroke-width:2px;
    classDef backend fill:#CFC,stroke:#333,stroke-width:2px;
    classDef route fill:#9CF,stroke:#333,stroke-width:2px;
    classDef controller fill:#FC9,stroke:#333,stroke-width:2px;
    classDef utility fill:#CF9,stroke:#333,stroke-width:2px;
    classDef template fill:#F9C,stroke:#333,stroke-width:2px;
    classDef container fill:#9F9,stroke:#333,stroke-width:2px;
    classDef cicd fill:#FF9,stroke:#333,stroke-width:2px;
    classDef external fill:#9FF,stroke:#333,stroke-width:2px;

    click API "https://github.com/yashksaini-coder/investo-server/blob/master/app.py"
    click AR "https://github.com/yashksaini-coder/investo-server/blob/master/routes/agentRoutes.py"
    click SR "https://github.com/yashksaini-coder/investo-server/blob/master/routes/stockRoutes.py"
    click A "https://github.com/yashksaini-coder/investo-server/blob/master/controllers/agents.py"
    click ASK "https://github.com/yashksaini-coder/investo-server/blob/master/controllers/ask.py"
    click SA "https://github.com/yashksaini-coder/investo-server/blob/master/controllers/stockAgent.py"
    click SN "https://github.com/yashksaini-coder/investo-server/blob/master/controllers/stockNews.py"
    click TS "https://github.com/yashksaini-coder/investo-server/blob/master/controllers/topStocks.py"
    click RC "https://github.com/yashksaini-coder/investo-server/blob/master/utils/redisCache.py"
    click T1 "https://github.com/yashksaini-coder/investo-server/blob/master/templates/base.html"
    click T2 "https://github.com/yashksaini-coder/investo-server/blob/master/templates/route.html"
    click D1 "https://github.com/yashksaini-coder/investo-server/tree/master/Dockerfile"
    click D2 "https://github.com/yashksaini-coder/investo-server/blob/master/docker-compose.yml"
    click D3 "https://github.com/yashksaini-coder/investo-server/blob/master/.dockerignore"
    click CICD "https://github.com/yashksaini-coder/investo-server/blob/master/.github/workflows/ping.yml"
```
