# vietdevsoft/stock-pro architecture

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

- Interactive diagram: https://gitdiagram.com/vietdevsoft/stock-pro
- Repository: https://github.com/vietdevsoft/stock-pro
- Video tour (about a minute): https://gitdiagram.com/vietdevsoft/stock-pro/video

## Overview

Stock Pro is a web-based inventory management system. Users browse product pages or register and sign in with CAPTCHA; authenticated users manage profiles, while managers and administrators use the admin area for products, categories, units, and inventory transactions. Administrators also manage users, audit logs, and site settings. FastAPI serves the pages and API routes; controllers delegate to services, which use database access for persistent state. The README documents Redis-backed CAPTCHA answers and inventory history, though those implementations were not fully sampled.

Main entry points: [`services/query_service.py`](https://github.com/vietdevsoft/stock-pro/blob/main/services/query_service.py) (Query gateway), [`static/js`](https://github.com/vietdevsoft/stock-pro/tree/main/static/js) (Browser JavaScript), [`controllers/product_controller.py`](https://github.com/vietdevsoft/stock-pro/blob/main/controllers/product_controller.py) (Product and stock API), [`main.py`](https://github.com/vietdevsoft/stock-pro/blob/main/main.py) (FastAPI app and pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_app["FastAPI app and pages<br/>[main.py]"]
  node_templates["Page templates"]
  node_client["Browser JavaScript"]
end

subgraph group_identity["Identity and profile"]
  node_authapi["Auth endpoints<br/>[auth_controller.py]"]
  node_authlogic["Auth workflows<br/>[auth_service.py]"]
  node_captchaapi["CAPTCHA endpoint"]
  node_captchalogic["CAPTCHA service<br/>[captcha_service.py]"]
  node_profileapi["Profile endpoints"]
  node_profilelogic["Profile service<br/>[profile_service.py]"]
  node_security["JWT security<br/>[security.py]"]
end

subgraph group_inventory["Inventory operations"]
  node_productapi["Product and stock API"]
  node_productlogic["Product and stock logic<br/>[product_service.py]"]
end

subgraph group_admin["System administration"]
  node_adminauth["Role authorization<br/>[admin_auth.py]"]
  node_useradmin["User administration<br/>[product_service.py]"]
  node_systemadmin["Audit and settings<br/>[product_service.py]"]
end

subgraph group_persistence["Persistence and access"]
  node_query["Query gateway<br/>[query_service.py]"]
  node_dbservice["Database connection"]
  node_postgres[("PostgreSQL<br/>[init.sql]")]
end

node_visitor(("Visitor / user"))
node_browser(("Web browser"))
node_redis[("Redis CAPTCHA store")]

node_visitor -->|"uses"| node_browser
node_browser -->|"requests pages"| node_app
node_app -->|"renders"| node_templates
node_browser -->|"runs scripts"| node_client
node_client -->|"submits auth"| node_authapi
node_client -->|"requests image"| node_captchaapi
node_client -->|"calls profile"| node_profileapi
node_client -->|"calls inventory"| node_productapi
node_app -->|"verifies page token"| node_security
node_app -->|"loads user info"| node_query
node_authapi -->|"delegates"| node_authlogic
node_authapi -->|"checks answer"| node_captchalogic
node_authapi -->|"creates token"| node_security
node_authlogic -->|"reads and writes"| node_query
node_captchaapi -->|"gets and saves answer"| node_captchalogic
node_captchalogic -->|"stores answers"| node_redis
node_profileapi -->|"verifies token"| node_security
node_profileapi -->|"delegates"| node_profilelogic
node_profileapi -->|"updates user"| node_query
node_profilelogic -->|"reads and writes"| node_query
node_productapi -->|"checks access"| node_adminauth
node_productapi -->|"delegates"| node_productlogic
node_productlogic -->|"queries data"| node_query
node_productlogic -->|"opens transactions"| node_dbservice
node_adminauth -->|"verifies token"| node_security
node_adminauth -->|"loads user role"| node_query
node_productapi -->|"routes user actions"| node_useradmin
node_productapi -->|"routes audit and settings"| node_systemadmin
node_query -->|"opens connection"| node_dbservice
node_dbservice -->|"connects"| node_postgres

click node_app "https://github.com/vietdevsoft/stock-pro/blob/main/main.py"
click node_templates "https://github.com/vietdevsoft/stock-pro/tree/main/templates"
click node_client "https://github.com/vietdevsoft/stock-pro/tree/main/static/js"
click node_authapi "https://github.com/vietdevsoft/stock-pro/blob/main/controllers/auth_controller.py"
click node_authlogic "https://github.com/vietdevsoft/stock-pro/blob/main/services/auth_service.py"
click node_captchaapi "https://github.com/vietdevsoft/stock-pro/blob/main/controllers/captcha_controller.py"
click node_captchalogic "https://github.com/vietdevsoft/stock-pro/blob/main/services/captcha_service.py"
click node_profileapi "https://github.com/vietdevsoft/stock-pro/blob/main/controllers/profile_controller.py"
click node_profilelogic "https://github.com/vietdevsoft/stock-pro/blob/main/services/profile_service.py"
click node_security "https://github.com/vietdevsoft/stock-pro/blob/main/utils/security.py"
click node_productapi "https://github.com/vietdevsoft/stock-pro/blob/main/controllers/product_controller.py"
click node_productlogic "https://github.com/vietdevsoft/stock-pro/blob/main/services/product_service.py"
click node_adminauth "https://github.com/vietdevsoft/stock-pro/blob/main/utils/admin_auth.py"
click node_useradmin "https://github.com/vietdevsoft/stock-pro/blob/main/services/product_service.py"
click node_systemadmin "https://github.com/vietdevsoft/stock-pro/blob/main/services/product_service.py"
click node_query "https://github.com/vietdevsoft/stock-pro/blob/main/services/query_service.py"
click node_dbservice "https://github.com/vietdevsoft/stock-pro/blob/main/services/database_service.py"
click node_postgres "https://github.com/vietdevsoft/stock-pro/blob/main/database/init.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_templates,node_client,node_visitor,node_browser toneBlue
class node_authapi,node_authlogic,node_captchaapi,node_captchalogic,node_profileapi,node_profilelogic,node_security,node_redis toneAmber
class node_productapi,node_productlogic toneMint
class node_adminauth,node_useradmin,node_systemadmin toneRose
class node_query,node_dbservice,node_postgres toneIndigo
```

## Components

### Web interface

- [FastAPI app and pages](https://github.com/vietdevsoft/stock-pro/blob/main/main.py): `main.py`
- [Page templates](https://github.com/vietdevsoft/stock-pro/tree/main/templates): `templates`
- [Browser JavaScript](https://github.com/vietdevsoft/stock-pro/tree/main/static/js): `static/js`

### Identity and profile

- [Auth endpoints](https://github.com/vietdevsoft/stock-pro/blob/main/controllers/auth_controller.py): `controllers/auth_controller.py`
- [Auth workflows](https://github.com/vietdevsoft/stock-pro/blob/main/services/auth_service.py): `services/auth_service.py`
- [CAPTCHA endpoint](https://github.com/vietdevsoft/stock-pro/blob/main/controllers/captcha_controller.py): `controllers/captcha_controller.py`
- [CAPTCHA service](https://github.com/vietdevsoft/stock-pro/blob/main/services/captcha_service.py): `services/captcha_service.py`
- [Profile endpoints](https://github.com/vietdevsoft/stock-pro/blob/main/controllers/profile_controller.py): `controllers/profile_controller.py`
- [Profile service](https://github.com/vietdevsoft/stock-pro/blob/main/services/profile_service.py): `services/profile_service.py`
- [JWT security](https://github.com/vietdevsoft/stock-pro/blob/main/utils/security.py): `utils/security.py`

### Inventory operations

- [Product and stock API](https://github.com/vietdevsoft/stock-pro/blob/main/controllers/product_controller.py): `controllers/product_controller.py`
- [Product and stock logic](https://github.com/vietdevsoft/stock-pro/blob/main/services/product_service.py): `services/product_service.py`

### System administration

- [Role authorization](https://github.com/vietdevsoft/stock-pro/blob/main/utils/admin_auth.py): `utils/admin_auth.py`
- [User administration](https://github.com/vietdevsoft/stock-pro/blob/main/services/product_service.py): `services/product_service.py`
- [Audit and settings](https://github.com/vietdevsoft/stock-pro/blob/main/services/product_service.py): `services/product_service.py`

### Persistence and access

- [Query gateway](https://github.com/vietdevsoft/stock-pro/blob/main/services/query_service.py): `services/query_service.py`
- [Database connection](https://github.com/vietdevsoft/stock-pro/blob/main/services/database_service.py): `services/database_service.py`
- [PostgreSQL](https://github.com/vietdevsoft/stock-pro/blob/main/database/init.sql): `database/init.sql`

### Other components

- **Visitor / user**
- **Web browser**
- **Redis CAPTCHA store**

## Connections

- Visitor / user → Web browser: uses
- Web browser → FastAPI app and pages: requests pages
- FastAPI app and pages → Page templates: renders
- Web browser → Browser JavaScript: runs scripts
- Browser JavaScript → Auth endpoints: submits auth
- Browser JavaScript → CAPTCHA endpoint: requests image
- Browser JavaScript → Profile endpoints: calls profile
- Browser JavaScript → Product and stock API: calls inventory
- FastAPI app and pages → JWT security: verifies page token
- FastAPI app and pages → Query gateway: loads user info
- Auth endpoints → Auth workflows: delegates
- Auth endpoints → CAPTCHA service: checks answer
- Auth endpoints → JWT security: creates token
- Auth workflows → Query gateway: reads and writes
- CAPTCHA endpoint → CAPTCHA service: gets and saves answer
- CAPTCHA service → Redis CAPTCHA store: stores answers
- Profile endpoints → JWT security: verifies token
- Profile endpoints → Profile service: delegates
- Profile endpoints → Query gateway: updates user
- Profile service → Query gateway: reads and writes
- Product and stock API → Role authorization: checks access
- Product and stock API → Product and stock logic: delegates
- Product and stock logic → Query gateway: queries data
- Product and stock logic → Database connection: opens transactions
- Role authorization → JWT security: verifies token
- Role authorization → Query gateway: loads user role
- Product and stock API → User administration: routes user actions
- Product and stock API → Audit and settings: routes audit and settings
- Query gateway → Database connection: opens connection
- Database connection → PostgreSQL: connects