# untangled-it-solutions/untangled-nexus-api architecture

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

- Interactive diagram: https://gitdiagram.com/untangled-it-solutions/untangled-nexus-api
- Repository: https://github.com/untangled-it-solutions/untangled-nexus-api

## Overview

Untangled Nexus API is a FastAPI backend for employee operations, product inventory, and quote/order tracking. Desktop clients call its route groups; session authentication resolves users and employees, while operational endpoints read or update shared MongoDB data. The main documented workflow spans login, attendance and task management, notifications, and dashboard summaries; commerce endpoints expose products and process orders. Core route modules are represented, including documented capabilities whose source excerpts were not provided. Relationships involving those unsampled modules are limited to documented registration or are left out.

Main entry points: [`app/main.py`](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/main.py) (FastAPI application), [`app/security.py`](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/security.py) (Session security), [`app/routers/dashboard.py`](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/dashboard.py) (Dashboard summary), [`app/routers/products.py`](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/products.py) (Products and stock)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API entry"]
  node_api["FastAPI application<br/>[main.py]"]
  node_health["Health checks<br/>[health.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

subgraph group_identity["Identity and access"]
  node_auth["Login and sessions<br/>[auth.py]"]
  node_security["Session security<br/>[security.py]"]
end

subgraph group_workforce["Workforce operations"]
  node_attendance["Attendance<br/>[attendance.py]"]
  node_dashboard["Dashboard summary<br/>[dashboard.py]"]
  node_tasks["Tasks<br/>[tasks.py]"]
  node_notifications["Notifications<br/>[notifications.py]"]
  node_approvals["Approvals<br/>[approvals.py]"]
  node_employees["Employee records<br/>[employees.py]"]
end

subgraph group_commerce["Commerce"]
  node_products["Products and stock<br/>[products.py]"]
  node_quotes["Quotes and orders<br/>[quotes.py]"]
end

subgraph group_data["Persistence"]
  node_mongo[("MongoDB")]
  node_dbclient["Database lifecycle<br/>[db.py]"]
end

node_client(("Desktop client"))

node_client -->|"sends requests"| node_api
node_api -->|"registers routes"| node_health
node_api -->|"registers routes"| node_auth
node_api -->|"registers routes"| node_dashboard
node_api -->|"registers routes"| node_attendance
node_api -->|"registers routes"| node_notifications
node_api -->|"registers routes"| node_tasks
node_api -->|"registers routes"| node_approvals
node_api -->|"registers routes"| node_quotes
node_api -->|"registers routes"| node_employees
node_api -->|"registers routes"| node_products
node_api -->|"loads settings"| node_settings
node_api -->|"opens and closes"| node_dbclient
node_dbclient -->|"reads configuration"| node_settings
node_dbclient -->|"connects client"| node_mongo
node_health -->|"checks readiness"| node_mongo
node_auth -->|"reads users; writes sessions"| node_mongo
node_auth -->|"verifies credentials"| node_security
node_security -->|"validates sessions"| node_mongo
node_attendance -->|"requires session"| node_security
node_attendance -->|"reads and updates records"| node_mongo
node_dashboard -->|"requires session"| node_security
node_dashboard -->|"queries workforce data"| node_mongo
node_dashboard -->|"reads cache setting"| node_settings
node_tasks -->|"requires session"| node_security
node_tasks -->|"manages assignments"| node_mongo
node_notifications -->|"requires session"| node_security
node_notifications -->|"manages notifications"| node_mongo
node_products -->|"requires session"| node_security
node_products -->|"manages inventory"| node_mongo
node_quotes -->|"reads and writes orders"| node_mongo
node_quotes -->|"decrements stock"| node_products

click node_api "https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/main.py"
click node_health "https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/health.py"
click node_settings "https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/config.py"
click node_auth "https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/auth.py"
click node_security "https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/security.py"
click node_attendance "https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/attendance.py"
click node_dashboard "https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/dashboard.py"
click node_tasks "https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/tasks.py"
click node_notifications "https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/notifications.py"
click node_approvals "https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/approvals.py"
click node_employees "https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/employees.py"
click node_products "https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/products.py"
click node_quotes "https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/quotes.py"
click node_dbclient "https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/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_api,node_health,node_settings,node_client toneBlue
class node_auth,node_security toneAmber
class node_attendance,node_dashboard,node_tasks,node_notifications,node_approvals,node_employees toneMint
class node_products,node_quotes toneRose
class node_mongo,node_dbclient toneIndigo
```

## Components

### API entry

- [FastAPI application](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/main.py): `app/main.py`
- [Health checks](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/health.py): `app/routers/health.py`
- [Runtime settings](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/config.py): `app/config.py`

### Identity and access

- [Login and sessions](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/auth.py): `app/routers/auth.py`
- [Session security](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/security.py): `app/security.py`

### Workforce operations

- [Attendance](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/attendance.py): `app/routers/attendance.py`
- [Dashboard summary](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/dashboard.py): `app/routers/dashboard.py`
- [Tasks](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/tasks.py): `app/routers/tasks.py`
- [Notifications](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/notifications.py): `app/routers/notifications.py`
- [Approvals](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/approvals.py): `app/routers/approvals.py`
- [Employee records](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/employees.py): `app/routers/employees.py`

### Commerce

- [Products and stock](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/products.py): `app/routers/products.py`
- [Quotes and orders](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/routers/quotes.py): `app/routers/quotes.py`

### Persistence

- **MongoDB**
- [Database lifecycle](https://github.com/untangled-it-solutions/untangled-nexus-api/blob/main/app/db.py): `app/db.py`

### Other components

- **Desktop client**

## Connections

- Desktop client → FastAPI application: sends requests
- FastAPI application → Health checks: registers routes (evidence: `app/main.py`)
- FastAPI application → Login and sessions: registers routes (evidence: `app/main.py`)
- FastAPI application → Dashboard summary: registers routes (evidence: `app/main.py`)
- FastAPI application → Attendance: registers routes (evidence: `app/main.py`)
- FastAPI application → Notifications: registers routes (evidence: `app/main.py`)
- FastAPI application → Tasks: registers routes (evidence: `app/main.py`)
- FastAPI application → Approvals: registers routes (evidence: `app/main.py`)
- FastAPI application → Quotes and orders: registers routes (evidence: `app/main.py`)
- FastAPI application → Employee records: registers routes (evidence: `app/main.py`)
- FastAPI application → Products and stock: registers routes (evidence: `app/main.py`)
- FastAPI application → Runtime settings: loads settings (evidence: `app/main.py`)
- FastAPI application → Database lifecycle: opens and closes (evidence: `app/main.py`)
- Database lifecycle → Runtime settings: reads configuration (evidence: `app/db.py`)
- Database lifecycle → MongoDB: connects client (evidence: `app/db.py`)
- Health checks → MongoDB: checks readiness
- Login and sessions → MongoDB: reads users; writes sessions (evidence: `app/routers/auth.py`)
- Login and sessions → Session security: verifies credentials (evidence: `app/security.py`)
- Session security → MongoDB: validates sessions (evidence: `app/security.py`)
- Attendance → Session security: requires session (evidence: `app/routers/attendance.py`)
- Attendance → MongoDB: reads and updates records (evidence: `app/routers/attendance.py`)
- Dashboard summary → Session security: requires session (evidence: `app/routers/dashboard.py`)
- Dashboard summary → MongoDB: queries workforce data (evidence: `app/routers/dashboard.py`)
- Dashboard summary → Runtime settings: reads cache setting (evidence: `app/routers/dashboard.py`)
- Tasks → Session security: requires session (evidence: `app/routers/tasks.py`)
- Tasks → MongoDB: manages assignments (evidence: `app/routers/tasks.py`)
- Notifications → Session security: requires session (evidence: `app/routers/notifications.py`)
- Notifications → MongoDB: manages notifications (evidence: `app/routers/notifications.py`)
- Products and stock → Session security: requires session (evidence: `app/routers/products.py`)
- Products and stock → MongoDB: manages inventory (evidence: `app/routers/products.py`)
- Quotes and orders → MongoDB: reads and writes orders (evidence: `app/routers/quotes.py`)
- Quotes and orders → Products and stock: decrements stock (evidence: `app/routers/quotes.py`)
