# mbs-23/fiberops-inventory-api architecture

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

- Interactive diagram: https://gitdiagram.com/mbs-23/fiberops-inventory-api
- Repository: https://github.com/mbs-23/fiberops-inventory-api

## Overview

FiberOps is a small Spring API for exchanges, fibre routes, and region-owned maintenance work orders. Clients call the exchange and route endpoints for inventory and use the work-order endpoints to queue, read, or open jobs; the work-order service sets the region within each transaction, while PostgreSQL row-level security enforces visibility and write scope. The README documents the API, migrations, route-length function, and RLS behavior. Some subsystem links are therefore documented rather than verified against unsampled implementation files.

Main entry points: [`src/main/java/io/github/mbs23/fiberops/workorder/WorkOrderService.java`](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/workorder/WorkOrderService.java) (Work-order operations), [`src/main/java/io/github/mbs23/fiberops/route/FibreRouteRepository.java`](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/route/FibreRouteRepository.java) (Route access), [`src/main/java/io/github/mbs23/fiberops/exchange/ExchangeController.java`](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/exchange/ExchangeController.java) (Exchange endpoints), [`src/main/java/io/github/mbs23/fiberops/exchange/ExchangeService.java`](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/exchange/ExchangeService.java) (Exchange operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_exchange["Exchange inventory"]
  node_exchange_api["Exchange endpoints"]
  node_exchange_service["Exchange operations"]
  node_exchange_repo["Exchange access"]
  node_exchange_entity["Exchange model<br/>[Exchange.java]"]
end

subgraph group_routes["Fibre routes"]
  node_route_api["Route endpoints"]
  node_route_service["Route queries"]
  node_route_repo["Route access"]
  node_route_entity["Route model<br/>[FibreRoute.java]"]
end

subgraph group_workorders["Work orders"]
  node_workorder_api["Work-order endpoints"]
  node_workorder_service["Work-order operations"]
  node_workorder_repo["Work-order access"]
  node_workorder_entity["Work-order model<br/>[WorkOrder.java]"]
end

subgraph group_persistence["Persistence and security"]
  node_region_scope["Transaction region scope<br/>[RegionScope.java]"]
  node_database[("PostgreSQL")]
  node_schema["Schema and function<br/>[V1__schema.sql]"]
  node_rls_policy["Work-order RLS"]
end

node_client(("API client"))

node_client -->|"requests"| node_exchange_api
node_client -->|"requests"| node_route_api
node_client -->|"requests"| node_workorder_api
node_exchange_api -->|"dispatches"| node_exchange_service
node_exchange_service -->|"queries and saves"| node_exchange_repo
node_exchange_repo -.->|"reads and writes"| node_database
node_route_api -->|"dispatches"| node_route_service
node_route_service -->|"queries"| node_route_repo
node_route_repo -->|"queries function"| node_database
node_workorder_api -->|"dispatches"| node_workorder_service
node_workorder_service -->|"sets region"| node_region_scope
node_region_scope -->|"sets transaction setting"| node_database
node_workorder_service -->|"queries and saves"| node_workorder_repo
node_workorder_service -->|"checks route"| node_route_repo
node_workorder_repo -.->|"queries and writes"| node_database
node_schema -->|"defines schema"| node_database
node_rls_policy -->|"enforces isolation"| node_database

click node_exchange_api "https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/exchange/ExchangeController.java"
click node_exchange_service "https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/exchange/ExchangeService.java"
click node_exchange_repo "https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/exchange/ExchangeRepository.java"
click node_exchange_entity "https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/exchange/Exchange.java"
click node_route_api "https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/route/FibreRouteController.java"
click node_route_service "https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/route/FibreRouteService.java"
click node_route_repo "https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/route/FibreRouteRepository.java"
click node_route_entity "https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/route/FibreRoute.java"
click node_workorder_api "https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/workorder/WorkOrderController.java"
click node_workorder_service "https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/workorder/WorkOrderService.java"
click node_workorder_repo "https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/workorder/WorkOrderRepository.java"
click node_workorder_entity "https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/workorder/WorkOrder.java"
click node_region_scope "https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/db/RegionScope.java"
click node_schema "https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/resources/db/migration/V1__schema.sql"
click node_rls_policy "https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/resources/db/migration/V3__work_order_rls.sql"

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_exchange_api,node_exchange_service,node_exchange_repo,node_exchange_entity,node_client toneBlue
class node_route_api,node_route_service,node_route_repo,node_route_entity toneAmber
class node_workorder_api,node_workorder_service,node_workorder_repo,node_workorder_entity toneMint
class node_region_scope,node_database,node_schema,node_rls_policy toneRose
```

## Components

### Exchange inventory

- [Exchange endpoints](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/exchange/ExchangeController.java): `src/main/java/io/github/mbs23/fiberops/exchange/ExchangeController.java`
- [Exchange operations](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/exchange/ExchangeService.java): `src/main/java/io/github/mbs23/fiberops/exchange/ExchangeService.java`
- [Exchange access](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/exchange/ExchangeRepository.java): `src/main/java/io/github/mbs23/fiberops/exchange/ExchangeRepository.java`
- [Exchange model](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/exchange/Exchange.java): `src/main/java/io/github/mbs23/fiberops/exchange/Exchange.java`

### Fibre routes

- [Route endpoints](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/route/FibreRouteController.java): `src/main/java/io/github/mbs23/fiberops/route/FibreRouteController.java`
- [Route queries](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/route/FibreRouteService.java): `src/main/java/io/github/mbs23/fiberops/route/FibreRouteService.java`
- [Route access](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/route/FibreRouteRepository.java): `src/main/java/io/github/mbs23/fiberops/route/FibreRouteRepository.java`
- [Route model](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/route/FibreRoute.java): `src/main/java/io/github/mbs23/fiberops/route/FibreRoute.java`

### Work orders

- [Work-order endpoints](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/workorder/WorkOrderController.java): `src/main/java/io/github/mbs23/fiberops/workorder/WorkOrderController.java`
- [Work-order operations](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/workorder/WorkOrderService.java): `src/main/java/io/github/mbs23/fiberops/workorder/WorkOrderService.java`
- [Work-order access](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/workorder/WorkOrderRepository.java): `src/main/java/io/github/mbs23/fiberops/workorder/WorkOrderRepository.java`
- [Work-order model](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/workorder/WorkOrder.java): `src/main/java/io/github/mbs23/fiberops/workorder/WorkOrder.java`

### Persistence and security

- [Transaction region scope](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/java/io/github/mbs23/fiberops/db/RegionScope.java): `src/main/java/io/github/mbs23/fiberops/db/RegionScope.java`
- **PostgreSQL**
- [Schema and function](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/resources/db/migration/V1__schema.sql): `src/main/resources/db/migration/V1__schema.sql`
- [Work-order RLS](https://github.com/mbs-23/fiberops-inventory-api/blob/main/src/main/resources/db/migration/V3__work_order_rls.sql): `src/main/resources/db/migration/V3__work_order_rls.sql`

### Other components

- **API client**

## Connections

- API client → Exchange endpoints: requests (evidence: `README.md`)
- API client → Route endpoints: requests (evidence: `README.md`)
- API client → Work-order endpoints: requests (evidence: `README.md`)
- Exchange endpoints → Exchange operations: dispatches (evidence: `src/main/java/io/github/mbs23/fiberops/exchange/ExchangeController.java`)
- Exchange operations → Exchange access: queries and saves (evidence: `src/main/java/io/github/mbs23/fiberops/exchange/ExchangeService.java`)
- Exchange access → PostgreSQL: reads and writes
- Route endpoints → Route queries: dispatches (evidence: `src/main/java/io/github/mbs23/fiberops/route/FibreRouteController.java`)
- Route queries → Route access: queries (evidence: `src/main/java/io/github/mbs23/fiberops/route/FibreRouteService.java`)
- Route access → PostgreSQL: queries function (evidence: `src/main/java/io/github/mbs23/fiberops/route/FibreRouteRepository.java`)
- Work-order endpoints → Work-order operations: dispatches (evidence: `src/main/java/io/github/mbs23/fiberops/workorder/WorkOrderController.java`)
- Work-order operations → Transaction region scope: sets region (evidence: `src/main/java/io/github/mbs23/fiberops/workorder/WorkOrderService.java`)
- Transaction region scope → PostgreSQL: sets transaction setting (evidence: `README.md`)
- Work-order operations → Work-order access: queries and saves (evidence: `src/main/java/io/github/mbs23/fiberops/workorder/WorkOrderService.java`)
- Work-order operations → Route access: checks route (evidence: `src/main/java/io/github/mbs23/fiberops/workorder/WorkOrderService.java`)
- Work-order access → PostgreSQL: queries and writes
- Schema and function → PostgreSQL: defines schema (evidence: `README.md`)
- Work-order RLS → PostgreSQL: enforces isolation (evidence: `README.md`)
