# kentchiu/stock architecture

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

- Interactive diagram: https://gitdiagram.com/kentchiu/stock
- Repository: https://github.com/kentchiu/stock

## Overview

##### Main Components
- Backend API – All code is located within the “api” folder. This includes:
- Configuration and database connectivity (api/stock/config/database.py)
- Data models and schemas (api/stock/models, api/stock/schemas)
- Repositories for data access (api/stock/repositories)
- Routers for API endpoints (api/stock/routers) built using FastAPI
- Business logic services (api/stock/services)
- Utility functions and exception handling (api/stock/utils)
- Tests under “api/tests” ensuring quality and reliability.
- Frontend Web Application – Present in the “web” directory:
- Built with ReactJS and TypeScript. Notice components, hooks, pages, and Recoil state management for UI and user interactions.
- Visual assets and configuration files (e.g., TailwindCSS configuration, nginx-proxy in web/nginx-proxy.conf) for deployment.
- Database – The application uses SQLite, with the database file managed in “api/data”. The README even includes commands to dump the DB contents.
- Infrastructure/Deployment – Docker Compose files and Dockerfiles in both “api” and “web” directories outline containerization for both frontend and backend.
- Documentation – The doc directory and images in the README offer insights into application features and are useful for illustrating the user interface as part of the overall architecture.

##### Relationships & Interactions
- The Frontend (ReactJS) communicates with the Backend API via HTTP endpoints exposed by FastAPI routers.
- The Backend serves client requests by invoking service layers that rely on repository logic to communicate with the SQLite database.
- Docker and Docker Compose orchestrate the deployment of the entire stack, ensuring backend and frontend containers work together seamlessly.
- Testing modules (unit & integration tests) interact with both backend repositories and endpoints to guarantee correct behavior.

##### Architectural Patterns & Technologies
- MVC/Microservice-like layer separation in the backend – models, routers (controllers), services (business logic), and repositories (data access).
- State management using RecoilJS on the frontend.
- API design leveraging RESTful principles with FastAPI.
- Containerization practices via Docker Compose.
- Emphasis on separation of concerns where the frontend, backend, and database are clearly delineated.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Web Application (ReactJS)"
        I["React Components"]:::frontend
        J["Pages"]:::frontend
        K["State Management (RecoilJS)"]:::frontend
        L["Configuration & Visual Assets"]:::frontend
    end

    subgraph "Backend API (FastAPI)"
        A["Config & DB Connectivity"]:::backend
        B["Data Models"]:::backend
        C["Data Schemas"]:::backend
        D["Repositories"]:::backend
        E["API Routers"]:::backend
        F["Business Logic Services"]:::backend
        G["Utility Functions & Exception Handling"]:::backend
        H["Backend Tests"]:::backend
    end

    M[(SQLite Database)]:::backend

    subgraph "Infrastructure/Deployment"
        N["Deployment (Docker Compose & Dockerfiles)"]:::deployment
    end

    O["Documentation"]:::doc

    %% Data Flow Connections
    J -->|"HTTP_Request"| E
    E -->|"invoke"| F
    F -->|"query"| D
    D -->|"data_fetch"| M
    A -->|"connects"| M
    C -->|"validates"| E
    B -->|"structs"| D
    H -.->|"tests"| E
    N -->|"deploys"| I
    N -->|"deploys"| A
    O -->|"docs"| N

    %% Click Events
    click A "https://github.com/kentchiu/stock/blob/master/api/stock/config/database.py"
    click B "https://github.com/kentchiu/stock/tree/master/api/stock/models"
    click C "https://github.com/kentchiu/stock/tree/master/api/stock/schemas"
    click D "https://github.com/kentchiu/stock/tree/master/api/stock/repositories"
    click E "https://github.com/kentchiu/stock/tree/master/api/stock/routers"
    click F "https://github.com/kentchiu/stock/tree/master/api/stock/services"
    click G "https://github.com/kentchiu/stock/blob/master/api/stock/utils/app_exceptions.py"
    click H "https://github.com/kentchiu/stock/tree/master/api/tests"
    click I "https://github.com/kentchiu/stock/tree/master/web/src/components"
    click J "https://github.com/kentchiu/stock/tree/master/web/src/pages"
    click K "https://github.com/kentchiu/stock/tree/master/web/src/recoil"
    click L "https://github.com/kentchiu/stock/blob/master/web/nginx-proxy.conf"
    click M "https://github.com/kentchiu/stock/tree/master/api/data"
    click N "https://github.com/kentchiu/stock/blob/master/docker-compose.yml"
    click N "https://github.com/kentchiu/stock/tree/master/api/Dockerfile"
    click N "https://github.com/kentchiu/stock/tree/master/web/Dockerfile"
    click O "https://github.com/kentchiu/stock/tree/master/doc"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef backend fill:#FDEBD0,stroke:#333,stroke-width:2px;
    classDef deployment fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef doc fill:#FFF9C4,stroke:#333,stroke-width:2px;
```
