# thilakarathnamtm/pss-backend architecture

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

- Interactive diagram: https://gitdiagram.com/thilakarathnamtm/pss-backend
- Repository: https://github.com/thilakarathnamtm/pss-backend

## Overview

This repository is a FastAPI backend for factory energy-cost management and machine scheduling. The visible workflow is user signup/login, authenticated factory and machine data access, then schedule optimization against tariffs, with optimization, dashboard, and report endpoints supporting results. The graph separates API dispatch, domain endpoints, persistence models, and internal services. The README provides no capability details, so feature coverage is based on the endpoint and module names in the source index; several endpoint implementations were not excerpted, so their links reflect indexed references only.

Main entry points: [`app/api/v1/endpoints/optimization.py`](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/endpoints/optimization.py) (Optimization endpoints), [`app/api/v1/api.py`](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/api.py) (API router), [`app/api/v1/endpoints/auth.py`](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/endpoints/auth.py) (Authentication), [`app/api/v1/endpoints/dashboard.py`](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/endpoints/dashboard.py) (Dashboard endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_application["Application<br/>[main.py]"]
  node_router["API router<br/>[api.py]"]
  node_auth["Authentication<br/>[auth.py]"]
end

subgraph group_domain["Factory operations"]
  node_factories["Factory endpoints<br/>[factories.py]"]
  node_machines["Machine endpoints<br/>[machines.py]"]
  node_tariffs["Tariff endpoints<br/>[tariffs.py]"]
  node_optimization["Optimization endpoints<br/>[optimization.py]"]
  node_dashboard["Dashboard endpoints<br/>[dashboard.py]"]
  node_reports["Report endpoints<br/>[reports.py]"]
  node_schemas["API schemas"]
end

subgraph group_data["Persistence"]
  node_factory_model["Factory model<br/>[factory.py]"]
  node_machine_model["Machine model<br/>[machine.py]"]
  node_tariff_model["Tariff model<br/>[tariff.py]"]
  node_optimization_model["Optimization models<br/>[optimization.py]"]
  node_report_model["Report model<br/>[report.py]"]
  node_user_model["User model<br/>[user.py]"]
end

subgraph group_services["Optimization services"]
  node_optimizer["Schedule optimizer<br/>[optimizer.py]"]
  node_cost["Cost calculations<br/>[cost.py]"]
end

subgraph group_platform["Runtime infrastructure"]
  node_dependencies["Request dependencies<br/>[deps.py]"]
  node_security["Token security<br/>[security.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_session["Database session<br/>[session.py]"]
  node_base["ORM base<br/>[base.py]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_application
node_application -->|"mounts routes"| node_router
node_router -->|"registers"| node_auth
node_router -->|"registers"| node_factories
node_router -->|"registers"| node_machines
node_router -->|"registers"| node_tariffs
node_router -->|"registers"| node_optimization
node_router -->|"registers"| node_dashboard
node_router -->|"registers"| node_reports
node_auth -->|"uses"| node_dependencies
node_auth -->|"uses"| node_security
node_auth -->|"queries"| node_user_model
node_auth -->|"creates"| node_factory_model
node_auth -->|"validates with"| node_schemas
node_factories -->|"references"| node_user_model
node_factories -->|"uses"| node_factory_model
node_factories -->|"validates with"| node_schemas
node_machines -->|"references"| node_user_model
node_machines -->|"uses"| node_machine_model
node_machines -->|"validates with"| node_schemas
node_tariffs -->|"uses"| node_tariff_model
node_tariffs -->|"validates with"| node_schemas
node_optimization -->|"uses"| node_dependencies
node_optimization -->|"uses"| node_factory_model
node_optimization -->|"uses"| node_machine_model
node_optimization -->|"uses"| node_tariff_model
node_optimization -->|"calls"| node_optimizer
node_optimization -->|"uses"| node_optimization_model
node_optimization -->|"uses"| node_report_model
node_optimization -->|"validates with"| node_schemas
node_dashboard -->|"uses"| node_user_model
node_dashboard -->|"uses"| node_factory_model
node_dashboard -->|"uses"| node_machine_model
node_dashboard -->|"uses"| node_optimization_model
node_dashboard -->|"returns"| node_schemas
node_reports -->|"references"| node_user_model
node_reports -->|"uses"| node_report_model
node_reports -->|"validates with"| node_schemas
node_dependencies -->|"opens session"| node_session
node_dependencies -->|"decodes token"| node_security
node_dependencies -->|"loads user"| node_user_model
node_security -->|"reads settings"| node_config
node_session -->|"reads settings"| node_config
node_optimizer -->|"reads inputs"| node_machine_model
node_optimizer -->|"reads inputs"| node_tariff_model
node_cost -->|"references"| node_machine_model
node_cost -->|"references"| node_tariff_model
node_factory_model -->|"inherits"| node_base

click node_application "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/main.py"
click node_router "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/api.py"
click node_auth "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/endpoints/auth.py"
click node_factories "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/endpoints/factories.py"
click node_machines "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/endpoints/machines.py"
click node_tariffs "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/endpoints/tariffs.py"
click node_optimization "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/endpoints/optimization.py"
click node_dashboard "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/endpoints/dashboard.py"
click node_reports "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/endpoints/reports.py"
click node_schemas "https://github.com/thilakarathnamtm/pss-backend/tree/main/app/schemas"
click node_factory_model "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/models/factory.py"
click node_machine_model "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/models/machine.py"
click node_tariff_model "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/models/tariff.py"
click node_optimization_model "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/models/optimization.py"
click node_report_model "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/models/report.py"
click node_user_model "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/models/user.py"
click node_optimizer "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/services/optimizer.py"
click node_cost "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/services/cost.py"
click node_dependencies "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/core/deps.py"
click node_security "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/core/security.py"
click node_config "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/core/config.py"
click node_session "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/db/session.py"
click node_base "https://github.com/thilakarathnamtm/pss-backend/blob/main/app/db/base.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_application,node_router,node_auth,node_client toneBlue
class node_factories,node_machines,node_tariffs,node_optimization,node_dashboard,node_reports,node_schemas toneAmber
class node_factory_model,node_machine_model,node_tariff_model,node_optimization_model,node_report_model,node_user_model toneMint
class node_optimizer,node_cost toneRose
class node_dependencies,node_security,node_config,node_session,node_base toneIndigo
```

## Components

### API and access

- [Application](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/main.py): `app/main.py`
- [API router](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/api.py): `app/api/v1/api.py`
- [Authentication](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/endpoints/auth.py): `app/api/v1/endpoints/auth.py`

### Factory operations

- [Factory endpoints](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/endpoints/factories.py): `app/api/v1/endpoints/factories.py`
- [Machine endpoints](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/endpoints/machines.py): `app/api/v1/endpoints/machines.py`
- [Tariff endpoints](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/endpoints/tariffs.py): `app/api/v1/endpoints/tariffs.py`
- [Optimization endpoints](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/endpoints/optimization.py): `app/api/v1/endpoints/optimization.py`
- [Dashboard endpoints](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/endpoints/dashboard.py): `app/api/v1/endpoints/dashboard.py`
- [Report endpoints](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/api/v1/endpoints/reports.py): `app/api/v1/endpoints/reports.py`
- [API schemas](https://github.com/thilakarathnamtm/pss-backend/tree/main/app/schemas): `app/schemas`

### Persistence

- [Factory model](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/models/factory.py): `app/models/factory.py`
- [Machine model](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/models/machine.py): `app/models/machine.py`
- [Tariff model](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/models/tariff.py): `app/models/tariff.py`
- [Optimization models](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/models/optimization.py): `app/models/optimization.py`
- [Report model](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/models/report.py): `app/models/report.py`
- [User model](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/models/user.py): `app/models/user.py`

### Optimization services

- [Schedule optimizer](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/services/optimizer.py): `app/services/optimizer.py`
- [Cost calculations](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/services/cost.py): `app/services/cost.py`

### Runtime infrastructure

- [Request dependencies](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/core/deps.py): `app/core/deps.py`
- [Token security](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/core/security.py): `app/core/security.py`
- [Configuration](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/core/config.py): `app/core/config.py`
- [Database session](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/db/session.py): `app/db/session.py`
- [ORM base](https://github.com/thilakarathnamtm/pss-backend/blob/main/app/db/base.py): `app/db/base.py`

### Other components

- **API client**

## Connections

- API client → Application: sends requests
- Application → API router: mounts routes (evidence: `app/main.py`)
- API router → Authentication: registers (evidence: `app/api/v1/api.py`)
- API router → Factory endpoints: registers (evidence: `app/api/v1/api.py`)
- API router → Machine endpoints: registers (evidence: `app/api/v1/api.py`)
- API router → Tariff endpoints: registers (evidence: `app/api/v1/api.py`)
- API router → Optimization endpoints: registers (evidence: `app/api/v1/api.py`)
- API router → Dashboard endpoints: registers (evidence: `app/api/v1/api.py`)
- API router → Report endpoints: registers (evidence: `app/api/v1/api.py`)
- Authentication → Request dependencies: uses (evidence: `app/api/v1/endpoints/auth.py`)
- Authentication → Token security: uses (evidence: `app/api/v1/endpoints/auth.py`)
- Authentication → User model: queries (evidence: `app/api/v1/endpoints/auth.py`)
- Authentication → Factory model: creates (evidence: `app/api/v1/endpoints/auth.py`)
- Authentication → API schemas: validates with (evidence: `app/api/v1/endpoints/auth.py`)
- Factory endpoints → User model: references (evidence: `app/api/v1/endpoints/factories.py`)
- Factory endpoints → Factory model: uses (evidence: `app/api/v1/endpoints/factories.py`)
- Factory endpoints → API schemas: validates with (evidence: `app/api/v1/endpoints/factories.py`)
- Machine endpoints → User model: references (evidence: `app/api/v1/endpoints/machines.py`)
- Machine endpoints → Machine model: uses (evidence: `app/api/v1/endpoints/machines.py`)
- Machine endpoints → API schemas: validates with (evidence: `app/api/v1/endpoints/machines.py`)
- Tariff endpoints → Tariff model: uses (evidence: `app/api/v1/endpoints/tariffs.py`)
- Tariff endpoints → API schemas: validates with (evidence: `app/api/v1/endpoints/tariffs.py`)
- Optimization endpoints → Request dependencies: uses (evidence: `app/api/v1/endpoints/optimization.py`)
- Optimization endpoints → Factory model: uses (evidence: `app/api/v1/endpoints/optimization.py`)
- Optimization endpoints → Machine model: uses (evidence: `app/api/v1/endpoints/optimization.py`)
- Optimization endpoints → Tariff model: uses (evidence: `app/api/v1/endpoints/optimization.py`)
- Optimization endpoints → Schedule optimizer: calls (evidence: `app/api/v1/endpoints/optimization.py`)
- Optimization endpoints → Optimization models: uses (evidence: `app/api/v1/endpoints/optimization.py`)
- Optimization endpoints → Report model: uses (evidence: `app/api/v1/endpoints/optimization.py`)
- Optimization endpoints → API schemas: validates with (evidence: `app/api/v1/endpoints/optimization.py`)
- Dashboard endpoints → User model: uses (evidence: `app/api/v1/endpoints/dashboard.py`)
- Dashboard endpoints → Factory model: uses (evidence: `app/api/v1/endpoints/dashboard.py`)
- Dashboard endpoints → Machine model: uses (evidence: `app/api/v1/endpoints/dashboard.py`)
- Dashboard endpoints → Optimization models: uses (evidence: `app/api/v1/endpoints/dashboard.py`)
- Dashboard endpoints → API schemas: returns (evidence: `app/api/v1/endpoints/dashboard.py`)
- Report endpoints → User model: references (evidence: `app/api/v1/endpoints/reports.py`)
- Report endpoints → Report model: uses (evidence: `app/api/v1/endpoints/reports.py`)
- Report endpoints → API schemas: validates with (evidence: `app/api/v1/endpoints/reports.py`)
- Request dependencies → Database session: opens session (evidence: `app/core/deps.py`)
- Request dependencies → Token security: decodes token (evidence: `app/core/deps.py`)
- Request dependencies → User model: loads user (evidence: `app/core/deps.py`)
- Token security → Configuration: reads settings (evidence: `app/core/security.py`)
- Database session → Configuration: reads settings (evidence: `app/db/session.py`)
- Schedule optimizer → Machine model: reads inputs (evidence: `app/services/optimizer.py`)
- Schedule optimizer → Tariff model: reads inputs (evidence: `app/services/optimizer.py`)
- Cost calculations → Machine model: references (evidence: `app/services/cost.py`)
- Cost calculations → Tariff model: references (evidence: `app/services/cost.py`)
- Factory model → ORM base: inherits (evidence: `app/models/factory.py`)
