# nakama-nova/nakama-desktop architecture

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

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

## Overview

NakamaDesk is a PyQt6 desktop ERP client. The main workflow is user sign-in, followed by retail billing: the POS looks up or creates a customer, loads inventory, submits a sale, then retrieves and opens its invoice. Other screens expose stock management, customer CRM, sales history, reporting/dashboard, attendance, and workforce operations. Domain services mediate UI-to-API work; an optional local outbox supports push/pull synchronization. Some screen and service wiring is represented from the README and tree because those sources were not sampled.

Main entry points: [`ui/main_window.py`](https://github.com/nakama-nova/nakama-desktop/blob/main/ui/main_window.py) (Main window), [`services/api_client.py`](https://github.com/nakama-nova/nakama-desktop/blob/main/services/api_client.py) (API client), [`ui/sales_screen.py`](https://github.com/nakama-nova/nakama-desktop/blob/main/ui/sales_screen.py) (Sales POS), [`services/sync_service.py`](https://github.com/nakama-nova/nakama-desktop/blob/main/services/sync_service.py) (Sync orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application and UI"]
  node_entry["App entry<br/>[main.py]"]
  node_login["Login window<br/>[login_window.py]"]
  node_workspace["Main window<br/>[main_window.py]"]
  node_pos["Sales POS<br/>[sales_screen.py]"]
  node_stock_ui["Inventory screen"]
  node_customers_ui["Customer CRM"]
  node_history_ui["Sales history"]
  node_dashboard_ui["Dashboard"]
  node_reports_ui["Reports<br/>[reports_screen.py]"]
  node_attendance_ui["Attendance"]
end

subgraph group_domain["Business services"]
  node_auth["Authentication<br/>[auth_service.py]"]
  node_sales["Sales operations<br/>[sales_service.py]"]
  node_customer["Customer operations"]
  node_inventory["Inventory operations"]
  node_report["Reporting<br/>[report_service.py]"]
  node_workforce["Workforce operations"]
end

subgraph group_transport["Network and session"]
  node_api["API client<br/>[api_client.py]"]
  node_session["Session state<br/>[session.py]"]
  node_events["Event bus<br/>[event_bus.py]"]
end

subgraph group_sync["Local synchronization"]
  node_sync_service["Sync orchestrator<br/>[sync_service.py]"]
  node_outbox["Outbox repository"]
  node_local_db[("Local database<br/>[local_db.py]")]
end

node_user(("Operator"))
node_backend["FurniBiz backend"]

node_user -->|"starts"| node_entry
node_entry -->|"opens"| node_login
node_user -->|"signs in"| node_login
node_login -->|"authenticates"| node_auth
node_auth -->|"requests login"| node_api
node_auth -->|"stores token"| node_session
node_login -->|"opens workspace"| node_workspace
node_workspace -->|"shows"| node_pos
node_workspace -->|"shows"| node_stock_ui
node_workspace -->|"shows"| node_customers_ui
node_workspace -->|"shows"| node_history_ui
node_workspace -->|"shows"| node_dashboard_ui
node_workspace -->|"shows"| node_reports_ui
node_workspace -->|"shows"| node_attendance_ui
node_pos -->|"loads items"| node_inventory
node_pos -->|"looks up or creates"| node_customer
node_pos -->|"submits sale"| node_sales
node_sales -->|"requests sales and invoices"| node_api
node_sales -->|"downloads invoice"| node_backend
node_inventory -->|"manages stock"| node_api
node_customers_ui -->|"manages customers"| node_customer
node_customer -->|"requests customer data"| node_api
node_history_ui -->|"loads history"| node_sales
node_dashboard_ui -->|"loads metrics"| node_report
node_reports_ui -->|"loads reports"| node_report
node_report -->|"requests reports"| node_api
node_attendance_ui -->|"records attendance"| node_workforce
node_workforce -->|"requests workforce data"| node_api
node_api -->|"sends HTTP requests"| node_backend
node_pos -->|"dispatches sale event"| node_events
node_events -->|"refreshes metrics"| node_dashboard_ui
node_sync_service -->|"reads and updates queue"| node_outbox
node_outbox -->|"reads and writes"| node_local_db
node_sync_service -.->|"pushes and pulls"| node_api
node_sync_service -->|"reads token"| node_session
node_sync_service -->|"uses database"| node_local_db

click node_entry "https://github.com/nakama-nova/nakama-desktop/blob/main/main.py"
click node_login "https://github.com/nakama-nova/nakama-desktop/blob/main/ui/login_window.py"
click node_workspace "https://github.com/nakama-nova/nakama-desktop/blob/main/ui/main_window.py"
click node_pos "https://github.com/nakama-nova/nakama-desktop/blob/main/ui/sales_screen.py"
click node_stock_ui "https://github.com/nakama-nova/nakama-desktop/blob/main/ui/inventory_window.py"
click node_customers_ui "https://github.com/nakama-nova/nakama-desktop/blob/main/ui/customers_screen.py"
click node_history_ui "https://github.com/nakama-nova/nakama-desktop/blob/main/ui/sales_history_screen.py"
click node_dashboard_ui "https://github.com/nakama-nova/nakama-desktop/blob/main/ui/dashboard_window.py"
click node_reports_ui "https://github.com/nakama-nova/nakama-desktop/blob/main/ui/reports_screen.py"
click node_attendance_ui "https://github.com/nakama-nova/nakama-desktop/blob/main/ui/attendance_screen.py"
click node_auth "https://github.com/nakama-nova/nakama-desktop/blob/main/services/auth_service.py"
click node_sales "https://github.com/nakama-nova/nakama-desktop/blob/main/services/sales_service.py"
click node_customer "https://github.com/nakama-nova/nakama-desktop/blob/main/services/customer_service.py"
click node_inventory "https://github.com/nakama-nova/nakama-desktop/blob/main/services/inventory_service.py"
click node_report "https://github.com/nakama-nova/nakama-desktop/blob/main/services/report_service.py"
click node_workforce "https://github.com/nakama-nova/nakama-desktop/blob/main/services/workforce_service.py"
click node_api "https://github.com/nakama-nova/nakama-desktop/blob/main/services/api_client.py"
click node_session "https://github.com/nakama-nova/nakama-desktop/blob/main/services/session.py"
click node_events "https://github.com/nakama-nova/nakama-desktop/blob/main/services/event_bus.py"
click node_sync_service "https://github.com/nakama-nova/nakama-desktop/blob/main/services/sync_service.py"
click node_outbox "https://github.com/nakama-nova/nakama-desktop/blob/main/database/outbox_repository.py"
click node_local_db "https://github.com/nakama-nova/nakama-desktop/blob/main/database/local_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_entry,node_login,node_workspace,node_pos,node_stock_ui,node_customers_ui,node_history_ui,node_dashboard_ui,node_reports_ui,node_attendance_ui toneBlue
class node_auth,node_sales,node_customer,node_inventory,node_report,node_workforce toneAmber
class node_api,node_session,node_events toneMint
class node_sync_service,node_outbox,node_local_db toneRose
class node_user,node_backend toneIndigo
```

## Components

### Application and UI

- [App entry](https://github.com/nakama-nova/nakama-desktop/blob/main/main.py): `main.py`
- [Login window](https://github.com/nakama-nova/nakama-desktop/blob/main/ui/login_window.py): `ui/login_window.py`
- [Main window](https://github.com/nakama-nova/nakama-desktop/blob/main/ui/main_window.py): `ui/main_window.py`
- [Sales POS](https://github.com/nakama-nova/nakama-desktop/blob/main/ui/sales_screen.py): `ui/sales_screen.py`
- [Inventory screen](https://github.com/nakama-nova/nakama-desktop/blob/main/ui/inventory_window.py): `ui/inventory_window.py`
- [Customer CRM](https://github.com/nakama-nova/nakama-desktop/blob/main/ui/customers_screen.py): `ui/customers_screen.py`
- [Sales history](https://github.com/nakama-nova/nakama-desktop/blob/main/ui/sales_history_screen.py): `ui/sales_history_screen.py`
- [Dashboard](https://github.com/nakama-nova/nakama-desktop/blob/main/ui/dashboard_window.py): `ui/dashboard_window.py`
- [Reports](https://github.com/nakama-nova/nakama-desktop/blob/main/ui/reports_screen.py): `ui/reports_screen.py`
- [Attendance](https://github.com/nakama-nova/nakama-desktop/blob/main/ui/attendance_screen.py): `ui/attendance_screen.py`

### Business services

- [Authentication](https://github.com/nakama-nova/nakama-desktop/blob/main/services/auth_service.py): `services/auth_service.py`
- [Sales operations](https://github.com/nakama-nova/nakama-desktop/blob/main/services/sales_service.py): `services/sales_service.py`
- [Customer operations](https://github.com/nakama-nova/nakama-desktop/blob/main/services/customer_service.py): `services/customer_service.py`
- [Inventory operations](https://github.com/nakama-nova/nakama-desktop/blob/main/services/inventory_service.py): `services/inventory_service.py`
- [Reporting](https://github.com/nakama-nova/nakama-desktop/blob/main/services/report_service.py): `services/report_service.py`
- [Workforce operations](https://github.com/nakama-nova/nakama-desktop/blob/main/services/workforce_service.py): `services/workforce_service.py`

### Network and session

- [API client](https://github.com/nakama-nova/nakama-desktop/blob/main/services/api_client.py): `services/api_client.py`
- [Session state](https://github.com/nakama-nova/nakama-desktop/blob/main/services/session.py): `services/session.py`
- [Event bus](https://github.com/nakama-nova/nakama-desktop/blob/main/services/event_bus.py): `services/event_bus.py`

### Local synchronization

- [Sync orchestrator](https://github.com/nakama-nova/nakama-desktop/blob/main/services/sync_service.py): `services/sync_service.py`
- [Outbox repository](https://github.com/nakama-nova/nakama-desktop/blob/main/database/outbox_repository.py): `database/outbox_repository.py`
- [Local database](https://github.com/nakama-nova/nakama-desktop/blob/main/database/local_db.py): `database/local_db.py`

### Other components

- **Operator**
- **FurniBiz backend**

## Connections

- Operator → App entry: starts
- App entry → Login window: opens
- Operator → Login window: signs in
- Login window → Authentication: authenticates
- Authentication → API client: requests login
- Authentication → Session state: stores token
- Login window → Main window: opens workspace
- Main window → Sales POS: shows
- Main window → Inventory screen: shows
- Main window → Customer CRM: shows
- Main window → Sales history: shows
- Main window → Dashboard: shows
- Main window → Reports: shows
- Main window → Attendance: shows
- Sales POS → Inventory operations: loads items
- Sales POS → Customer operations: looks up or creates
- Sales POS → Sales operations: submits sale
- Sales operations → API client: requests sales and invoices
- Sales operations → FurniBiz backend: downloads invoice
- Inventory operations → API client: manages stock
- Customer CRM → Customer operations: manages customers
- Customer operations → API client: requests customer data
- Sales history → Sales operations: loads history
- Dashboard → Reporting: loads metrics
- Reports → Reporting: loads reports
- Reporting → API client: requests reports
- Attendance → Workforce operations: records attendance
- Workforce operations → API client: requests workforce data
- API client → FurniBiz backend: sends HTTP requests
- Sales POS → Event bus: dispatches sale event
- Event bus → Dashboard: refreshes metrics
- Sync orchestrator → Outbox repository: reads and updates queue
- Outbox repository → Local database: reads and writes
- Sync orchestrator → API client: pushes and pulls
- Sync orchestrator → Session state: reads token
- Sync orchestrator → Local database: uses database