# nakama-nova/nakamadesk-backend architecture

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

- Interactive diagram: https://gitdiagram.com/nakama-nova/nakamadesk-backend
- Repository: https://github.com/nakama-nova/nakamadesk-backend

## Overview

NakamaDesk is the FastAPI backend for a furniture-business ERP, serving desktop clients with authentication, inventory, sales and billing, customer management, production, workforce, and analytics capabilities. The main flow is client request → registered API route → business service → SQLAlchemy-backed persistence; sales, purchasing, and production also affect inventory through its movement engine. The README describes the API/service split, while sampled source confirms app registration, authentication, inventory movement calls, and database/repository patterns. Most route-to-service links below follow documented module responsibilities; unsampled route implementations may differ.

Main entry points: [`app/main.py`](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/main.py) (FastAPI application), [`app/repositories/sqlalchemy_repo.py`](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/repositories/sqlalchemy_repo.py) (Repositories and unit of work), [`app/services/inventory_service.py`](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/inventory_service.py) (Inventory engine), [`app/services/production_service.py`](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/production_service.py) (Production service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API surface"]
  node_app["FastAPI application<br/>[main.py]"]
  node_auth_api["Authentication routes<br/>[auth.py]"]
  node_items_api["Item routes<br/>[items.py]"]
  node_sales_api["Sales routes<br/>[sales.py]"]
  node_customers_api["Customer routes<br/>[customers.py]"]
  node_invoices_api["Invoice routes<br/>[invoices.py]"]
  node_dashboard_api["Dashboard routes<br/>[dashboard.py]"]
  node_reports_api["Reports routes<br/>[reports.py]"]
  node_orders_api["Order routes<br/>[orders.py]"]
  node_production_api["Production routes<br/>[production.py]"]
  node_purchases_api["Purchase routes<br/>[purchases.py]"]
  node_workforce_api["Attendance and wages<br/>[attendance.py]"]
  node_sync_api["Sync routes<br/>[sync.py]"]
end

subgraph group_commerce["Sales and customers"]
  node_sales_service["Sales service<br/>[sales_service.py]"]
  node_customer_service["Customer service"]
  node_invoice_service["Invoice service<br/>[invoice_service.py]"]
  node_pdf_service["PDF generation"]
  node_analytics["Analytics service"]
end

subgraph group_operations["Inventory and operations"]
  node_inventory["Inventory engine"]
  node_orders_service["Order service<br/>[order_service.py]"]
  node_production_service["Production service"]
  node_bom_service["Bill of materials<br/>[bom_service.py]"]
  node_purchase_service["Purchase service"]
  node_raw_material_service["Raw materials"]
  node_workforce_service["Workforce service"]
end

subgraph group_platform["Platform and persistence"]
  node_auth_service["Authentication service<br/>[auth_service.py]"]
  node_sync_service["Sync service<br/>[sync_service.py]"]
  node_uow["Repositories and unit of work<br/>[sqlalchemy_repo.py]"]
  node_database[("PostgreSQL database<br/>[session.py]")]
end

node_client(("Desktop client"))

node_client -->|"sends requests"| node_app
node_app -->|"registers routes"| node_auth_api
node_app -->|"registers routes"| node_items_api
node_app -->|"registers routes"| node_sales_api
node_app -->|"registers routes"| node_customers_api
node_app -->|"registers routes"| node_invoices_api
node_app -->|"registers routes"| node_dashboard_api
node_app -->|"registers routes"| node_reports_api
node_app -->|"registers routes"| node_orders_api
node_app -->|"registers routes"| node_production_api
node_app -->|"registers routes"| node_purchases_api
node_app -->|"registers routes"| node_workforce_api
node_app -->|"registers routes"| node_sync_api
node_auth_api -->|"calls"| node_auth_service
node_auth_api -->|"queries users"| node_uow
node_auth_service -->|"persists users"| node_uow
node_items_api -->|"delegates item work"| node_inventory
node_sales_api -->|"delegates sales"| node_sales_service
node_sales_service -->|"records stock movement"| node_inventory
node_customers_api -->|"delegates CRM"| node_customer_service
node_invoices_api -->|"requests invoices"| node_invoice_service
node_invoice_service -->|"generates PDF"| node_pdf_service
node_dashboard_api -->|"requests metrics"| node_analytics
node_reports_api -->|"requests reports"| node_analytics
node_orders_api -->|"delegates orders"| node_orders_service
node_production_api -->|"delegates jobs"| node_production_service
node_production_service -->|"consumes and adds stock"| node_inventory
node_production_service -.->|"uses material requirements"| node_bom_service
node_purchases_api -->|"delegates purchasing"| node_purchase_service
node_purchase_service -.->|"adds received stock"| node_inventory
node_purchase_service -.->|"manages materials"| node_raw_material_service
node_workforce_api -->|"delegates attendance"| node_workforce_service
node_sync_api -->|"delegates sync"| node_sync_service
node_sync_service -->|"applies operations"| node_uow
node_inventory -->|"reads and writes records"| node_uow
node_production_service -->|"reads and writes jobs"| node_uow
node_workforce_service -->|"records attendance and wages"| node_uow
node_uow -->|"persists transactions"| node_database

click node_app "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/main.py"
click node_auth_api "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/auth.py"
click node_auth_service "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/auth_service.py"
click node_items_api "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/items.py"
click node_inventory "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/inventory_service.py"
click node_sales_api "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/sales.py"
click node_sales_service "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/sales_service.py"
click node_customers_api "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/customers.py"
click node_customer_service "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/customer_service.py"
click node_invoices_api "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/invoices.py"
click node_invoice_service "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/invoice_service.py"
click node_pdf_service "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/invoice_pdf_service.py"
click node_dashboard_api "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/dashboard.py"
click node_reports_api "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/reports.py"
click node_analytics "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/analytics_service.py"
click node_orders_api "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/orders.py"
click node_orders_service "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/order_service.py"
click node_production_api "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/production.py"
click node_production_service "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/production_service.py"
click node_bom_service "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/bom_service.py"
click node_purchases_api "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/purchases.py"
click node_purchase_service "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/purchase_service.py"
click node_raw_material_service "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/raw_material_service.py"
click node_workforce_api "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/attendance.py"
click node_workforce_service "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/workforce_service.py"
click node_sync_api "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/sync.py"
click node_sync_service "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/sync_service.py"
click node_uow "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/repositories/sqlalchemy_repo.py"
click node_database "https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/db/session.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_app,node_auth_api,node_items_api,node_sales_api,node_customers_api,node_invoices_api,node_dashboard_api,node_reports_api,node_orders_api,node_production_api,node_purchases_api,node_workforce_api,node_sync_api,node_client toneBlue
class node_sales_service,node_customer_service,node_invoice_service,node_pdf_service,node_analytics toneAmber
class node_inventory,node_orders_service,node_production_service,node_bom_service,node_purchase_service,node_raw_material_service,node_workforce_service toneMint
class node_auth_service,node_sync_service,node_uow,node_database toneRose
```

## Components

### API surface

- [FastAPI application](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/main.py): `app/main.py`
- [Authentication routes](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/auth.py): `app/api/auth.py`
- [Item routes](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/items.py): `app/api/items.py`
- [Sales routes](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/sales.py): `app/api/sales.py`
- [Customer routes](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/customers.py): `app/api/customers.py`
- [Invoice routes](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/invoices.py): `app/api/invoices.py`
- [Dashboard routes](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/dashboard.py): `app/api/dashboard.py`
- [Reports routes](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/reports.py): `app/api/reports.py`
- [Order routes](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/orders.py): `app/api/orders.py`
- [Production routes](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/production.py): `app/api/production.py`
- [Purchase routes](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/purchases.py): `app/api/purchases.py`
- [Attendance and wages](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/attendance.py): `app/api/attendance.py`
- [Sync routes](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/api/sync.py): `app/api/sync.py`

### Sales and customers

- [Sales service](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/sales_service.py): `app/services/sales_service.py`
- [Customer service](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/customer_service.py): `app/services/customer_service.py`
- [Invoice service](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/invoice_service.py): `app/services/invoice_service.py`
- [PDF generation](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/invoice_pdf_service.py): `app/services/invoice_pdf_service.py`
- [Analytics service](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/analytics_service.py): `app/services/analytics_service.py`

### Inventory and operations

- [Inventory engine](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/inventory_service.py): `app/services/inventory_service.py`
- [Order service](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/order_service.py): `app/services/order_service.py`
- [Production service](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/production_service.py): `app/services/production_service.py`
- [Bill of materials](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/bom_service.py): `app/services/bom_service.py`
- [Purchase service](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/purchase_service.py): `app/services/purchase_service.py`
- [Raw materials](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/raw_material_service.py): `app/services/raw_material_service.py`
- [Workforce service](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/workforce_service.py): `app/services/workforce_service.py`

### Platform and persistence

- [Authentication service](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/auth_service.py): `app/services/auth_service.py`
- [Sync service](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/services/sync_service.py): `app/services/sync_service.py`
- [Repositories and unit of work](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/repositories/sqlalchemy_repo.py): `app/repositories/sqlalchemy_repo.py`
- [PostgreSQL database](https://github.com/nakama-nova/nakamadesk-backend/blob/main/app/db/session.py): `app/db/session.py`

### Other components

- **Desktop client**

## Connections

- Desktop client → FastAPI application: sends requests
- FastAPI application → Authentication routes: registers routes
- FastAPI application → Item routes: registers routes
- FastAPI application → Sales routes: registers routes
- FastAPI application → Customer routes: registers routes
- FastAPI application → Invoice routes: registers routes
- FastAPI application → Dashboard routes: registers routes
- FastAPI application → Reports routes: registers routes
- FastAPI application → Order routes: registers routes
- FastAPI application → Production routes: registers routes
- FastAPI application → Purchase routes: registers routes
- FastAPI application → Attendance and wages: registers routes
- FastAPI application → Sync routes: registers routes
- Authentication routes → Authentication service: calls
- Authentication routes → Repositories and unit of work: queries users
- Authentication service → Repositories and unit of work: persists users
- Item routes → Inventory engine: delegates item work
- Sales routes → Sales service: delegates sales
- Sales service → Inventory engine: records stock movement
- Customer routes → Customer service: delegates CRM
- Invoice routes → Invoice service: requests invoices
- Invoice service → PDF generation: generates PDF
- Dashboard routes → Analytics service: requests metrics
- Reports routes → Analytics service: requests reports
- Order routes → Order service: delegates orders
- Production routes → Production service: delegates jobs
- Production service → Inventory engine: consumes and adds stock
- Production service → Bill of materials: uses material requirements
- Purchase routes → Purchase service: delegates purchasing
- Purchase service → Inventory engine: adds received stock
- Purchase service → Raw materials: manages materials
- Attendance and wages → Workforce service: delegates attendance
- Sync routes → Sync service: delegates sync
- Sync service → Repositories and unit of work: applies operations
- Inventory engine → Repositories and unit of work: reads and writes records
- Production service → Repositories and unit of work: reads and writes jobs
- Workforce service → Repositories and unit of work: records attendance and wages
- Repositories and unit of work → PostgreSQL database: persists transactions