# thevickypedia/fastapiauthenticator architecture

> Architecture diagram of the GitHub repository thevickypedia/fastapiauthenticator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thevickypedia/fastapiauthenticator
- Repository: https://github.com/thevickypedia/fastapiauthenticator

## Overview

##### Project type and purpose
- This is an open-source Python library (“FastAPIAuthenticator”) that plugs into a user’s FastAPI application to add username/password authentication to selected HTTP or WebSocket routes.
- The README and samples show how a developer calls `fastapiauthenticator.protect(...)` to wrap existing route handlers.

##### File structure
- Top-level:
- `fastapiauthenticator/` – the core library package
- `base/` – likely boilerplate or example scripts (e.g., `api.py`, `api.sh`)
- `samples/` – example FastAPI apps demonstrating usage
- Configuration: `pyproject.toml`, `requirements.txt`, `pre-commit-config.yaml`
- Inside `fastapiauthenticator/`:
- `endpoints.py` – login, logout, unauthorized handlers
- `service.py` – orchestration of authentication logic
- `secure.py` – credential verification, hashing, session management
- `models.py`, `enums.py` – Pydantic models & enums for parameters, responses
- `utils.py` – cookie/session utilities
- `templates/` – HTML pages for login, unauthorized, session info
- No database adapter; sessions are likely in-memory or signed cookies.

##### Key insights from the README
- One-line integration: a developer calls `protect(app, Parameters(...))`
- Supports both HTTP (`APIRoute`) and WebSocket (`APIWebSocketRoute`)
- Samples show form-post login flow and programmatic API use
- No complex microservices—this is a middleware/plugin library.

##### Main components
a. Client (Browser or WebSocket client)
b. FastAPI Application (developer’s code)
c. FastAPIAuthenticator Library
- Protect wrapper
- Service layer
- Secure layer
- Endpoints (login/logout/unauthorized)
- Templates (HTML)
- Pydantic Models & Enums
- Utils (cookie/session)
d. Protected Route Handler (user’s private function)
e. Optional External Systems (e.g., user storage if extended)

##### Relationships and data flow
1. Client → FastAPI app
2. Incoming request hits Protect wrapper (middleware or decorator)
3. Wrapper checks session via `secure` + `utils`
4. If session valid → call original protected route → return response
5. If not valid → redirect to Authenticator login endpoint
6. Client posts credentials → `endpoints.login` → `service.validate_user` → `secure.verify_credentials`
7. On success → set session cookie (`utils`) → redirect back to protected route
8. On failure → serve unauthorized template

##### Architectural patterns & design principles
- Separation of concerns:
- Protect wrapper isolates authentication logic
- `service.py` orchestrates flow, calls `secure.py`
- `secure.py` handles all low-level security (hashing, session tokens)
- `endpoints.py` only defines HTTP/WebSocket routes for auth
- Plug-in/Middleware pattern: integrates into FastAPI’s routing
- Template-based views for HTML forms

##### Technologies & frameworks
- Python 3.11+
- FastAPI (Starlette under the hood)
- Pydantic for data models
- Jinja2 (via FastAPI templates)
- Standard library / itsdangerous or cookie signing for sessions

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client (Browser/WebSocket)"]:::client
    FastAPIApp["FastAPI Application"]:::app
    Protected["Protected Route Handler"]:::handler

    subgraph "FastAPIAuthenticator Library"
        Protect["Protect Wrapper"]:::auth
        Service["service.py"]:::auth
        Secure["secure.py"]:::auth
        Endpoints["endpoints.py"]:::auth
        Utils["utils.py"]:::auth
        ModelsEnums["models.py / enums.py"]:::auth
        Templates["templates/ (HTML)"]:::auth
    end

    Client -->|HTTP Request| FastAPIApp
    Client ---|WebSocket Request| FastAPIApp
    FastAPIApp --> Protect
    Protect --> Protected
    Protected -->|Response| Client

    Protect -->|invalid session| Endpoints
    Endpoints --> Service
    Service --> Secure
    Secure --> Utils
    Utils --> Endpoints
    Endpoints -->|login form / redirect| Client

    classDef client fill:#FFD966,stroke:#D8A31A,color:#000;
    classDef app fill:#A9D08E,stroke:#6AA84F,color:#000;
    classDef auth fill:#9FC5E8,stroke:#6D9EEB,color:#000;
    classDef handler fill:#EA9999,stroke:#CC0000,color:#000;

    click Protect "https://github.com/thevickypedia/fastapiauthenticator/blob/main/fastapiauthenticator/__init__.py"
    click Service "https://github.com/thevickypedia/fastapiauthenticator/blob/main/fastapiauthenticator/service.py"
    click Secure "https://github.com/thevickypedia/fastapiauthenticator/blob/main/fastapiauthenticator/secure.py"
    click Endpoints "https://github.com/thevickypedia/fastapiauthenticator/blob/main/fastapiauthenticator/endpoints.py"
    click Utils "https://github.com/thevickypedia/fastapiauthenticator/blob/main/fastapiauthenticator/utils.py"
    click ModelsEnums "https://github.com/thevickypedia/fastapiauthenticator/blob/main/fastapiauthenticator/models.py"
    click Endpoints "https://github.com/thevickypedia/fastapiauthenticator/blob/main/fastapiauthenticator/enums.py"
    click Templates "https://github.com/thevickypedia/fastapiauthenticator/blob/main/fastapiauthenticator/templates/index.html"
    click Templates "https://github.com/thevickypedia/fastapiauthenticator/blob/main/fastapiauthenticator/templates/unauthorized.html"
    click Templates "https://github.com/thevickypedia/fastapiauthenticator/blob/main/fastapiauthenticator/templates/session.html"
    click Samples1 "https://github.com/thevickypedia/fastapiauthenticator/blob/main/samples/sample1.py"
    click Samples2 "https://github.com/thevickypedia/fastapiauthenticator/blob/main/samples/sample2.py"
    click SamplesIndex "https://github.com/thevickypedia/fastapiauthenticator/blob/main/samples/index.html"
    click BaseAPI "https://github.com/thevickypedia/fastapiauthenticator/blob/main/base/api.py"
    click BaseScript "https://github.com/thevickypedia/fastapiauthenticator/blob/main/base/api.sh"
```
