# pesu-dev/auth architecture

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

- Interactive diagram: https://gitdiagram.com/pesu-dev/auth
- Repository: https://github.com/pesu-dev/auth

## Overview

PESUAuth is a privacy-preserving API that validates PESU Academy credentials and optionally returns profile data. The main flow validates an incoming request, authenticates against PESU Academy, optionally fetches and parses a profile, and returns the result without storing credentials or personal data. Separate routes provide API documentation, health checks, a repository redirect, and metrics. The graph reflects the supplied excerpts and README; some endpoint wiring and documentation modules were not sampled, so uncertain connections are omitted.

Main entry points: [`app/app.py`](https://github.com/pesu-dev/auth/blob/dev/app/app.py) (FastAPI Entrypoint), [`app/pesu.py`](https://github.com/pesu-dev/auth/blob/dev/app/pesu.py) (PESU Authentication), [`app/metrics/collector.py`](https://github.com/pesu-dev/auth/blob/dev/app/metrics/collector.py) (Metrics Collector), [`app/metrics/middleware.py`](https://github.com/pesu-dev/auth/blob/dev/app/metrics/middleware.py) (Request Instrumentation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Workflow"]
  node_app["FastAPI Entrypoint<br/>[app.py]"]
  node_request["Request Validation<br/>[request.py]"]
  node_profile["Profile Response<br/>[profile.py]"]
end

subgraph group_upstream["PESU Integration"]
  node_pesu["PESU Authentication<br/>[pesu.py]"]
  node_auth_errors["Authentication Errors<br/>[authentication.py]"]
end

subgraph group_monitoring["Monitoring"]
  node_metrics_middleware["Request Instrumentation<br/>[middleware.py]"]
  node_collector[("Metrics Collector<br/>[collector.py]")]
  node_metrics_auth["Metrics Token Guard<br/>[auth.py]"]
  node_metrics_models["Metrics Models<br/>[metrics.py]"]
  node_prometheus["Prometheus Renderer<br/>[prometheus.py]"]
end

subgraph group_support["API Support"]
  node_health_docs["Health Documentation<br/>[health.py]"]
  node_metrics_docs["Metrics Documentation<br/>[metrics.py]"]
  node_auth_docs["Authentication Documentation<br/>[authenticate.py]"]
  node_readme_docs["Repository Redirect<br/>[readme.py]"]
  node_docs_base["API Documentation Base<br/>[base.py]"]
end

node_caller(("API Caller"))
node_academy["PESU Academy"]

node_caller -->|"sends request"| node_app
node_app -->|"validates input"| node_request
node_app -->|"authenticates"| node_pesu
node_pesu -->|"sends login"| node_academy
node_pesu -->|"fetches profile"| node_academy
node_pesu -->|"builds profile"| node_profile
node_pesu -->|"raises errors"| node_auth_errors
node_app -->|"returns result"| node_caller
node_app -->|"installs middleware"| node_metrics_middleware
node_metrics_middleware -->|"records traffic"| node_collector
node_pesu -->|"records upstream activity"| node_collector
node_caller -->|"presents token"| node_metrics_auth
node_app -->|"guards metrics route"| node_metrics_auth
node_app -->|"exposes metrics"| node_collector
node_collector -->|"snapshots counters"| node_metrics_models
node_app -->|"renders metrics"| node_prometheus
node_app -->|"documents health"| node_health_docs
node_app -->|"documents metrics"| node_metrics_docs
node_app -->|"documents authentication"| node_auth_docs
node_app -->|"documents redirect"| node_readme_docs
node_app -->|"builds API docs"| node_docs_base

click node_app "https://github.com/pesu-dev/auth/blob/dev/app/app.py"
click node_request "https://github.com/pesu-dev/auth/blob/dev/app/models/request.py"
click node_pesu "https://github.com/pesu-dev/auth/blob/dev/app/pesu.py"
click node_profile "https://github.com/pesu-dev/auth/blob/dev/app/models/profile.py"
click node_auth_errors "https://github.com/pesu-dev/auth/blob/dev/app/exceptions/authentication.py"
click node_metrics_middleware "https://github.com/pesu-dev/auth/blob/dev/app/metrics/middleware.py"
click node_collector "https://github.com/pesu-dev/auth/blob/dev/app/metrics/collector.py"
click node_metrics_auth "https://github.com/pesu-dev/auth/blob/dev/app/metrics/auth.py"
click node_metrics_models "https://github.com/pesu-dev/auth/blob/dev/app/models/metrics.py"
click node_prometheus "https://github.com/pesu-dev/auth/blob/dev/app/metrics/prometheus.py"
click node_health_docs "https://github.com/pesu-dev/auth/blob/dev/app/docs/health.py"
click node_metrics_docs "https://github.com/pesu-dev/auth/blob/dev/app/docs/metrics.py"
click node_auth_docs "https://github.com/pesu-dev/auth/blob/dev/app/docs/authenticate.py"
click node_readme_docs "https://github.com/pesu-dev/auth/blob/dev/app/docs/readme.py"
click node_docs_base "https://github.com/pesu-dev/auth/blob/dev/app/docs/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_app,node_request,node_profile toneBlue
class node_pesu,node_auth_errors toneAmber
class node_metrics_middleware,node_collector,node_metrics_auth,node_metrics_models,node_prometheus,node_caller toneMint
class node_health_docs,node_metrics_docs,node_auth_docs,node_readme_docs,node_docs_base toneRose
class node_academy toneIndigo
```

## Components

### API Workflow

- [FastAPI Entrypoint](https://github.com/pesu-dev/auth/blob/dev/app/app.py): `app/app.py`
- [Request Validation](https://github.com/pesu-dev/auth/blob/dev/app/models/request.py): `app/models/request.py`
- [Profile Response](https://github.com/pesu-dev/auth/blob/dev/app/models/profile.py): `app/models/profile.py`

### PESU Integration

- [PESU Authentication](https://github.com/pesu-dev/auth/blob/dev/app/pesu.py): `app/pesu.py`
- [Authentication Errors](https://github.com/pesu-dev/auth/blob/dev/app/exceptions/authentication.py): `app/exceptions/authentication.py`

### Monitoring

- [Request Instrumentation](https://github.com/pesu-dev/auth/blob/dev/app/metrics/middleware.py): `app/metrics/middleware.py`
- [Metrics Collector](https://github.com/pesu-dev/auth/blob/dev/app/metrics/collector.py): `app/metrics/collector.py`
- [Metrics Token Guard](https://github.com/pesu-dev/auth/blob/dev/app/metrics/auth.py): `app/metrics/auth.py`
- [Metrics Models](https://github.com/pesu-dev/auth/blob/dev/app/models/metrics.py): `app/models/metrics.py`
- [Prometheus Renderer](https://github.com/pesu-dev/auth/blob/dev/app/metrics/prometheus.py): `app/metrics/prometheus.py`

### API Support

- [Health Documentation](https://github.com/pesu-dev/auth/blob/dev/app/docs/health.py): `app/docs/health.py`
- [Metrics Documentation](https://github.com/pesu-dev/auth/blob/dev/app/docs/metrics.py): `app/docs/metrics.py`
- [Authentication Documentation](https://github.com/pesu-dev/auth/blob/dev/app/docs/authenticate.py): `app/docs/authenticate.py`
- [Repository Redirect](https://github.com/pesu-dev/auth/blob/dev/app/docs/readme.py): `app/docs/readme.py`
- [API Documentation Base](https://github.com/pesu-dev/auth/blob/dev/app/docs/base.py): `app/docs/base.py`

### Other components

- **API Caller**
- **PESU Academy**

## Connections

- API Caller → FastAPI Entrypoint: sends request
- FastAPI Entrypoint → Request Validation: validates input
- FastAPI Entrypoint → PESU Authentication: authenticates
- PESU Authentication → PESU Academy: sends login
- PESU Authentication → PESU Academy: fetches profile
- PESU Authentication → Profile Response: builds profile
- PESU Authentication → Authentication Errors: raises errors
- FastAPI Entrypoint → API Caller: returns result
- FastAPI Entrypoint → Request Instrumentation: installs middleware
- Request Instrumentation → Metrics Collector: records traffic
- PESU Authentication → Metrics Collector: records upstream activity
- API Caller → Metrics Token Guard: presents token
- FastAPI Entrypoint → Metrics Token Guard: guards metrics route
- FastAPI Entrypoint → Metrics Collector: exposes metrics
- Metrics Collector → Metrics Models: snapshots counters
- FastAPI Entrypoint → Prometheus Renderer: renders metrics
- FastAPI Entrypoint → Health Documentation: documents health
- FastAPI Entrypoint → Metrics Documentation: documents metrics
- FastAPI Entrypoint → Authentication Documentation: documents authentication
- FastAPI Entrypoint → Repository Redirect: documents redirect
- FastAPI Entrypoint → API Documentation Base: builds API docs