# harshbodani/stockmate architecture

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

- Interactive diagram: https://gitdiagram.com/harshbodani/stockmate
- Repository: https://github.com/harshbodani/stockmate

## Overview

StockMate is a web-based business and inventory system. Users sign in, then use configured screens, dashboard views, POS, or the assistant; browser requests reach the Java API, which applies role checks and delegates data operations to PostgreSQL. Database functions implement the documented transactional business rules, while document services generate PDFs. The README also describes CRM, purchasing, invoicing, quality, manufacturing, projects, HR, and POS. Some backend and frontend wiring is unsampled; edges below are limited to excerpts or README statements.

Main entry points: [`backend/src/main/java/com/stockmate/Api.java`](https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Api.java) (API routes), [`backend/src/main/java/com/stockmate/Main.java`](https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Main.java) (HTTP server startup), [`backend/src/main/java/com/stockmate/Assistant.java`](https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Assistant.java) (Assistant service), [`frontend/js/app.js`](https://github.com/harshbodani/stockmate/blob/main/frontend/js/app.js) (Screen router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_screens["Configured screens<br/>[config.js]"]
  node_app["Screen router<br/>[app.js]"]
  node_dashboard["Dashboard<br/>[dashboard.js]"]
  node_pos["POS terminal<br/>[pos.js]"]
  node_voice["Voice assistant UI<br/>[voice.js]"]
end

subgraph group_server["Java server"]
  node_main["HTTP server startup<br/>[Main.java]"]
  node_api["API routes<br/>[Api.java]"]
  node_auth["Sessions and sign-in<br/>[Auth.java]"]
  node_permissions["Role permissions<br/>[Permissions.java]"]
  node_database_interface["Database interface<br/>[Database.java]"]
  node_jdbc["JDBC connection pool<br/>[JdbcDatabase.java]"]
  node_json["JSON parsing<br/>[Json.java]"]
end

subgraph group_business["Business data"]
  node_postgres[("PostgreSQL tables<br/>[schema.sql]")]
  node_functions[("Business functions<br/>[functions.sql]")]
end

subgraph group_documents["Assistant and documents"]
  node_assistant["Assistant service<br/>[Assistant.java]"]
  node_documents_service["PDF documents<br/>[Documents.java]"]
  node_pdf["PDF renderer<br/>[Pdf.java]"]
end

node_user(("Business user"))
node_openjarvis["OpenJarvis"]

node_user -->|"uses"| node_app
node_screens -->|"configures"| node_app
node_app -.->|"requests data"| node_api
node_pos -->|"requests sales data"| node_api
node_voice -->|"posts questions"| node_api
node_main -->|"creates"| node_jdbc
node_main -->|"routes HTTP"| node_api
node_api -->|"checks sessions"| node_auth
node_api -->|"checks roles"| node_permissions
node_api -->|"answers questions"| node_assistant
node_api -->|"queries"| node_database_interface
node_main -->|"initializes"| node_database_interface
node_jdbc -->|"executes SQL"| node_postgres
node_functions -->|"enforce business rules"| node_postgres
node_assistant -->|"reads business data"| node_database_interface
node_assistant -->|"optionally queries"| node_openjarvis
node_api -.->|"serves PDFs"| node_documents_service
node_documents_service -->|"renders documents"| node_pdf
node_api -->|"parses requests"| node_json
node_auth -->|"parses login data"| node_json

click node_screens "https://github.com/harshbodani/stockmate/blob/main/frontend/js/config.js"
click node_app "https://github.com/harshbodani/stockmate/blob/main/frontend/js/app.js"
click node_dashboard "https://github.com/harshbodani/stockmate/blob/main/frontend/js/dashboard.js"
click node_pos "https://github.com/harshbodani/stockmate/blob/main/frontend/js/pos.js"
click node_voice "https://github.com/harshbodani/stockmate/blob/main/frontend/js/voice.js"
click node_main "https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Main.java"
click node_api "https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Api.java"
click node_auth "https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Auth.java"
click node_permissions "https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Permissions.java"
click node_database_interface "https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Database.java"
click node_jdbc "https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/JdbcDatabase.java"
click node_json "https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Json.java"
click node_postgres "https://github.com/harshbodani/stockmate/blob/main/db/schema.sql"
click node_functions "https://github.com/harshbodani/stockmate/blob/main/db/functions.sql"
click node_assistant "https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Assistant.java"
click node_documents_service "https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Documents.java"
click node_pdf "https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Pdf.java"

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_screens,node_app,node_dashboard,node_pos,node_voice,node_user toneBlue
class node_main,node_api,node_auth,node_permissions,node_database_interface,node_jdbc,node_json toneAmber
class node_postgres,node_functions toneMint
class node_assistant,node_documents_service,node_pdf toneRose
class node_openjarvis toneIndigo
```

## Components

### Web interface

- [Configured screens](https://github.com/harshbodani/stockmate/blob/main/frontend/js/config.js): `frontend/js/config.js`
- [Screen router](https://github.com/harshbodani/stockmate/blob/main/frontend/js/app.js): `frontend/js/app.js`
- [Dashboard](https://github.com/harshbodani/stockmate/blob/main/frontend/js/dashboard.js): `frontend/js/dashboard.js`
- [POS terminal](https://github.com/harshbodani/stockmate/blob/main/frontend/js/pos.js): `frontend/js/pos.js`
- [Voice assistant UI](https://github.com/harshbodani/stockmate/blob/main/frontend/js/voice.js): `frontend/js/voice.js`

### Java server

- [HTTP server startup](https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Main.java): `backend/src/main/java/com/stockmate/Main.java`
- [API routes](https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Api.java): `backend/src/main/java/com/stockmate/Api.java`
- [Sessions and sign-in](https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Auth.java): `backend/src/main/java/com/stockmate/Auth.java`
- [Role permissions](https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Permissions.java): `backend/src/main/java/com/stockmate/Permissions.java`
- [Database interface](https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Database.java): `backend/src/main/java/com/stockmate/Database.java`
- [JDBC connection pool](https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/JdbcDatabase.java): `backend/src/main/java/com/stockmate/JdbcDatabase.java`
- [JSON parsing](https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Json.java): `backend/src/main/java/com/stockmate/Json.java`

### Business data

- [PostgreSQL tables](https://github.com/harshbodani/stockmate/blob/main/db/schema.sql): `db/schema.sql`
- [Business functions](https://github.com/harshbodani/stockmate/blob/main/db/functions.sql): `db/functions.sql`

### Assistant and documents

- [Assistant service](https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Assistant.java): `backend/src/main/java/com/stockmate/Assistant.java`
- [PDF documents](https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Documents.java): `backend/src/main/java/com/stockmate/Documents.java`
- [PDF renderer](https://github.com/harshbodani/stockmate/blob/main/backend/src/main/java/com/stockmate/Pdf.java): `backend/src/main/java/com/stockmate/Pdf.java`

### Other components

- **Business user**
- **OpenJarvis**

## Connections

- Business user → Screen router: uses (evidence: `README.md`)
- Configured screens → Screen router: configures (evidence: `README.md`)
- Screen router → API routes: requests data
- POS terminal → API routes: requests sales data (evidence: `frontend/js/pos.js`)
- Voice assistant UI → API routes: posts questions (evidence: `frontend/js/voice.js`)
- HTTP server startup → JDBC connection pool: creates (evidence: `backend/src/main/java/com/stockmate/Main.java`)
- HTTP server startup → API routes: routes HTTP (evidence: `backend/src/main/java/com/stockmate/Main.java`)
- API routes → Sessions and sign-in: checks sessions (evidence: `backend/src/main/java/com/stockmate/Api.java`)
- API routes → Role permissions: checks roles (evidence: `backend/src/main/java/com/stockmate/Api.java`)
- API routes → Assistant service: answers questions (evidence: `backend/src/main/java/com/stockmate/Api.java`)
- API routes → Database interface: queries (evidence: `backend/src/main/java/com/stockmate/Api.java`)
- HTTP server startup → Database interface: initializes (evidence: `backend/src/main/java/com/stockmate/Main.java`)
- JDBC connection pool → PostgreSQL tables: executes SQL (evidence: `README.md`)
- Business functions → PostgreSQL tables: enforce business rules (evidence: `README.md`)
- Assistant service → Database interface: reads business data (evidence: `backend/src/main/java/com/stockmate/Assistant.java`)
- Assistant service → OpenJarvis: optionally queries (evidence: `backend/src/main/java/com/stockmate/Assistant.java`)
- API routes → PDF documents: serves PDFs (evidence: `backend/src/main/java/com/stockmate/Api.java`)
- PDF documents → PDF renderer: renders documents (evidence: `backend/src/main/java/com/stockmate/Documents.java`)
- API routes → JSON parsing: parses requests (evidence: `backend/src/main/java/com/stockmate/Api.java`)
- Sessions and sign-in → JSON parsing: parses login data (evidence: `backend/src/main/java/com/stockmate/Auth.java`)
