# festrada-it/smartstock architecture

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

- Interactive diagram: https://gitdiagram.com/festrada-it/smartstock
- Repository: https://github.com/festrada-it/smartstock

## Overview

SmartStock supports retail inventory workflows: users manage catalog and staff, record sales and stock purchases, and view demand, stockout, alert, and summary predictions. The frontend calls separate core and analytics REST services; core owns authentication and inventory transactions, while analytics reads product, sales, and parameter data to produce forecasts. Sampled source confirms several core service-to-repository calls and analytics route-to-data/model calls; other links are included only where documented in the README.

Main entry points: [`core-service/src/main/java/com/smartstock/core/controller`](https://github.com/festrada-it/smartstock/tree/main/core-service/src/main/java/com/smartstock/core/controller) (Core REST API), [`analytics-service/app/main.py`](https://github.com/festrada-it/smartstock/blob/main/analytics-service/app/main.py) (Analytics API), [`frontend/js/api.js`](https://github.com/festrada-it/smartstock/blob/main/frontend/js/api.js) (API client), [`frontend/js`](https://github.com/festrada-it/smartstock/tree/main/frontend/js) (Inventory UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_web_ui["Inventory UI"]
  node_web_api["API client<br/>[api.js]"]
end

subgraph group_core["Inventory core"]
  node_core_api["Core REST API"]
  node_auth["JWT authentication<br/>[AuthService.java]"]
  node_jwt["JWT service<br/>[JwtService.java]"]
  node_catalog["Product catalog"]
  node_categories["Categories"]
  node_sales["Sales recording<br/>[VentaService.java]"]
  node_purchases["Stock purchases<br/>[CompraService.java]"]
  node_users["User administration"]
  node_parameters["Business parameters"]
  node_core_security["Access control"]
end

subgraph group_analytics["Predictive analytics"]
  node_analytics_api["Analytics API<br/>[main.py]"]
  node_forecast["Demand and stockout analysis<br/>[prediccion.py]"]
  node_analytics_auth["Token validation<br/>[auth.py]"]
  node_analytics_data["Analytics data access<br/>[db.py]"]
end

subgraph group_data["Persistence"]
  node_postgres[("PostgreSQL")]
end

node_retail_user(("Retail user"))

node_retail_user -->|"uses"| node_web_ui
node_web_ui -->|"requests data"| node_web_api
node_web_api -->|"REST/JSON + JWT"| node_core_api
node_web_api -->|"REST/JSON + JWT"| node_analytics_api
node_core_api -->|"routes login"| node_auth
node_core_api -->|"routes catalog"| node_catalog
node_core_api -->|"routes sales"| node_sales
node_core_api -->|"routes purchases"| node_purchases
node_core_api -->|"routes user admin"| node_users
node_core_api -->|"serves category API"| node_categories
node_core_api -->|"serves parameter API"| node_parameters
node_auth -->|"generates token"| node_jwt
node_catalog -.->|"reads and writes"| node_postgres
node_sales -.->|"records sale and stock"| node_postgres
node_purchases -.->|"updates stock"| node_postgres
node_users -.->|"reads and writes"| node_postgres
node_categories -.->|"reads and writes"| node_postgres
node_parameters -.->|"reads and writes"| node_postgres
node_analytics_api -->|"requires token"| node_analytics_auth
node_analytics_api -->|"loads inventory and sales"| node_analytics_data
node_analytics_api -->|"analyzes demand"| node_forecast
node_analytics_data -->|"reads analytics data"| node_postgres
node_core_security -.->|"protects endpoints"| node_core_api
node_jwt -->|"shared JWT secret"| node_analytics_auth

click node_web_ui "https://github.com/festrada-it/smartstock/tree/main/frontend/js"
click node_web_api "https://github.com/festrada-it/smartstock/blob/main/frontend/js/api.js"
click node_core_api "https://github.com/festrada-it/smartstock/tree/main/core-service/src/main/java/com/smartstock/core/controller"
click node_auth "https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/service/AuthService.java"
click node_jwt "https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/security/JwtService.java"
click node_catalog "https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/service/ProductoService.java"
click node_categories "https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/controller/CategoriaController.java"
click node_sales "https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/service/VentaService.java"
click node_purchases "https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/service/CompraService.java"
click node_users "https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/service/UsuarioService.java"
click node_parameters "https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/controller/ParametroController.java"
click node_core_security "https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/config/SecurityConfig.java"
click node_analytics_api "https://github.com/festrada-it/smartstock/blob/main/analytics-service/app/main.py"
click node_forecast "https://github.com/festrada-it/smartstock/blob/main/analytics-service/app/prediccion.py"
click node_analytics_auth "https://github.com/festrada-it/smartstock/blob/main/analytics-service/app/auth.py"
click node_analytics_data "https://github.com/festrada-it/smartstock/blob/main/analytics-service/app/db.py"

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_web_ui,node_web_api,node_retail_user toneBlue
class node_core_api,node_auth,node_jwt,node_catalog,node_categories,node_sales,node_purchases,node_users,node_parameters,node_core_security toneAmber
class node_analytics_api,node_forecast,node_analytics_auth,node_analytics_data toneMint
class node_postgres toneRose
```

## Components

### Web application

- [Inventory UI](https://github.com/festrada-it/smartstock/tree/main/frontend/js): `frontend/js`
- [API client](https://github.com/festrada-it/smartstock/blob/main/frontend/js/api.js): `frontend/js/api.js`

### Inventory core

- [Core REST API](https://github.com/festrada-it/smartstock/tree/main/core-service/src/main/java/com/smartstock/core/controller): `core-service/src/main/java/com/smartstock/core/controller`
- [JWT authentication](https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/service/AuthService.java): `core-service/src/main/java/com/smartstock/core/service/AuthService.java`
- [JWT service](https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/security/JwtService.java): `core-service/src/main/java/com/smartstock/core/security/JwtService.java`
- [Product catalog](https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/service/ProductoService.java): `core-service/src/main/java/com/smartstock/core/service/ProductoService.java`
- [Categories](https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/controller/CategoriaController.java): `core-service/src/main/java/com/smartstock/core/controller/CategoriaController.java`
- [Sales recording](https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/service/VentaService.java): `core-service/src/main/java/com/smartstock/core/service/VentaService.java`
- [Stock purchases](https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/service/CompraService.java): `core-service/src/main/java/com/smartstock/core/service/CompraService.java`
- [User administration](https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/service/UsuarioService.java): `core-service/src/main/java/com/smartstock/core/service/UsuarioService.java`
- [Business parameters](https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/controller/ParametroController.java): `core-service/src/main/java/com/smartstock/core/controller/ParametroController.java`
- [Access control](https://github.com/festrada-it/smartstock/blob/main/core-service/src/main/java/com/smartstock/core/config/SecurityConfig.java): `core-service/src/main/java/com/smartstock/core/config/SecurityConfig.java`

### Predictive analytics

- [Analytics API](https://github.com/festrada-it/smartstock/blob/main/analytics-service/app/main.py): `analytics-service/app/main.py`
- [Demand and stockout analysis](https://github.com/festrada-it/smartstock/blob/main/analytics-service/app/prediccion.py): `analytics-service/app/prediccion.py`
- [Token validation](https://github.com/festrada-it/smartstock/blob/main/analytics-service/app/auth.py): `analytics-service/app/auth.py`
- [Analytics data access](https://github.com/festrada-it/smartstock/blob/main/analytics-service/app/db.py): `analytics-service/app/db.py`

### Persistence

- **PostgreSQL**

### Other components

- **Retail user**

## Connections

- Retail user → Inventory UI: uses (evidence: `README.md`)
- Inventory UI → API client: requests data (evidence: `README.md`)
- API client → Core REST API: REST/JSON + JWT (evidence: `README.md`)
- API client → Analytics API: REST/JSON + JWT (evidence: `README.md`)
- Core REST API → JWT authentication: routes login
- Core REST API → Product catalog: routes catalog (evidence: `core-service/src/main/java/com/smartstock/core/controller/ProductoController.java`)
- Core REST API → Sales recording: routes sales (evidence: `README.md`)
- Core REST API → Stock purchases: routes purchases (evidence: `README.md`)
- Core REST API → User administration: routes user admin (evidence: `core-service/src/main/java/com/smartstock/core/controller/UsuarioController.java`)
- Core REST API → Categories: serves category API (evidence: `README.md`)
- Core REST API → Business parameters: serves parameter API (evidence: `README.md`)
- JWT authentication → JWT service: generates token (evidence: `core-service/src/main/java/com/smartstock/core/service/AuthService.java`)
- Product catalog → PostgreSQL: reads and writes
- Sales recording → PostgreSQL: records sale and stock
- Stock purchases → PostgreSQL: updates stock
- User administration → PostgreSQL: reads and writes
- Categories → PostgreSQL: reads and writes
- Business parameters → PostgreSQL: reads and writes
- Analytics API → Token validation: requires token (evidence: `analytics-service/app/main.py`)
- Analytics API → Analytics data access: loads inventory and sales (evidence: `analytics-service/app/main.py`)
- Analytics API → Demand and stockout analysis: analyzes demand (evidence: `analytics-service/app/main.py`)
- Analytics data access → PostgreSQL: reads analytics data (evidence: `README.md`)
- Access control → Core REST API: protects endpoints
- JWT service → Token validation: shared JWT secret (evidence: `core-service/src/main/java/com/smartstock/core/security/JwtService.java`)