# adarshmalviy/shadowid architecture

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

- Interactive diagram: https://gitdiagram.com/adarshmalviy/shadowid
- Repository: https://github.com/adarshmalviy/shadowid

## Overview

##### Project Type and Purpose
- ShadowID is a standalone backend authentication service built with FastAPI in Python. It serves as a privacy-focused OAuth2/JWT-based auth system, issuing anonymous identifiers, access/refresh tokens (with encryption and rotation), and enforcing RBAC and rate-limiting. It relies on PostgreSQL for persistence and Redis for storing encrypted refresh tokens and rate-limit counters.

##### File Structure Analysis
- Top level:
- app/ – main FastAPI application package
- migrations/ – database migration scripts (Alembic-style)
- pyproject.toml & requirements.txt – dependency specs
- app/ subpackages:
- routers/ – HTTP endpoints (auth, user, health, spotlight_doc)
- services/ – Redis service abstraction
- db/ – ORM configuration and data models
- auth.py, security.py – OAuth2 and JWT utilities
- config.py – environment and secrets configuration
- loggers.py – logging setup
- main.py – FastAPI app instantiation and router inclusion

##### Key Architectural Insights from the README
- OAuth2/JWT flow with token rotation and encryption
- RBAC enforced at endpoint level
- Rate-limiting on login
- Future extensibility for Zero-Knowledge Proofs, context-aware RBAC, federated learning, MFA

##### Diagramming the System
a. Main Components
1. Client (Web/Mobile)
2. API Gateway (FastAPI app)
– Routers: /register, /token, /refresh, /spotlight_doc, /health
– Security middleware (OAuth2, RBAC, rate limiter)
– Services layer: RedisService
– Data layer: SQLAlchemy ORM
3. PostgreSQL Database
4. Redis Cache
5. (External) OAuth2 Identity Providers (if any)
b. Relationships & Interactions
- Client → FastAPI routers via HTTPS
- Routers → Services (business logic) → DB/Redis
- Token issuance: routers call auth utilities for JWT creation
- Refresh: services handle token lookup/encryption in Redis → rotate tokens
- DB migrations update PostgreSQL schema
c. Architectural Patterns & Principles
- Layered architecture: API layer (routers) → service layer → data access layer
- Separation of concerns: auth, config, logging, data models in distinct modules
- Stateless API with external stateful stores (PostgreSQL, Redis)
- Security best practices: token encryption, rate-limiting, RBAC
d. Key Technologies
- FastAPI (HTTP framework)
- Python OAuth2 utilities & PyJWT
- SQLAlchemy (ORM)
- Alembic (migrations)
- Redis (token store & rate limiter)
- PostgreSQL (relational DB)

##### Final Recommendations
- Break the FastAPI service into logical bounded contexts: Authentication, User Management, Health Check, Spotlight Documents
- Configuration/loading of environment variables at startup

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    Client(("Web/Mobile Client")):::external
    OAuthProviders(("External OAuth2 Providers")):::external

    %% API Gateway Layer
    subgraph "API Gateway (FastAPI Service)"
        direction TB
        MainApp["FastAPI Application"]:::code
        Config["Configuration Loader"]:::code
        Loggers["Logging Setup"]:::code
        Security["Security Middleware (OAuth2, RBAC, Rate Limiting)"]:::code
        AuthUtils["OAuth2/JWT Utils"]:::code

        subgraph "Routers"
            direction TB
            AuthRouter["Auth Router (/register, /token, /refresh)"]:::code
            UserRouter["User Router"]:::code
            HealthRouter["Health Check Router"]:::code
            SpotlightRouter["Spotlight Document Router"]:::code
        end

        Service["RedisService (Token Store & Rate Limiter)"]:::code

        subgraph "Data Access Layer"
            direction TB
            ORMConfig["ORM Configuration"]:::code
            Models["Data Models"]:::code
        end
    end

    %% Deployment / Migrations & Dependencies
    subgraph "Deployment Artifacts"
        direction TB
        Migrations["DB Migrations (Alembic)"]:::code
        Deps["Dependency Specs (pyproject.toml, requirements.txt)"]:::code
    end

    %% Data Stores
    PostgreSQL[(PostgreSQL Database)]:::datastore
    Redis[(Redis Cache)]:::datastore

    %% Interactions
    Client -->|"HTTPS Requests"| AuthRouter
    Client -->|"HTTPS Requests"| UserRouter
    Client -->|"HTTPS Requests"| HealthRouter
    Client -->|"HTTPS Requests"| SpotlightRouter
    AuthRouter -->|calls| AuthUtils
    AuthRouter -->|uses| Security
    AuthRouter -->|delegates| Service
    UserRouter -->|uses| Security
    UserRouter -->|calls| Service
    HealthRouter -->|calls| Loggers
    SpotlightRouter -->|uses| Security
    SpotlightRouter -->|calls| Service

    MainApp -->|includes| Config
    MainApp -->|includes| Loggers
    MainApp -->|includes| Security
    MainApp -->|includes| AuthUtils
    MainApp -->|includes| Routers
    MainApp -->|initializes| ORMConfig
    MainApp -->|initializes| Service

    Service -->|reads/writes| Redis
    ORMConfig -->|migrates/schema| PostgreSQL
    Models -->|defines schema| PostgreSQL

    Migrations -->|applies| PostgreSQL
    Deps -->|required by| MainApp

    OAuthProviders -->|"federated login"| AuthUtils

    %% Click Events
    click MainApp "https://github.com/adarshmalviy/shadowid/blob/main/app/main.py"
    click Config "https://github.com/adarshmalviy/shadowid/blob/main/app/config.py"
    click Loggers "https://github.com/adarshmalviy/shadowid/blob/main/app/loggers.py"
    click AuthUtils "https://github.com/adarshmalviy/shadowid/blob/main/app/auth.py"
    click Security "https://github.com/adarshmalviy/shadowid/blob/main/app/security.py"
    click AuthRouter "https://github.com/adarshmalviy/shadowid/blob/main/app/routers/auth.py"
    click UserRouter "https://github.com/adarshmalviy/shadowid/blob/main/app/routers/user.py"
    click HealthRouter "https://github.com/adarshmalviy/shadowid/blob/main/app/routers/health.py"
    click SpotlightRouter "https://github.com/adarshmalviy/shadowid/blob/main/app/routers/spotlight_doc.py"
    click Service "https://github.com/adarshmalviy/shadowid/blob/main/app/services/redis_service.py"
    click ORMConfig "https://github.com/adarshmalviy/shadowid/blob/main/app/db/orm_config.py"
    click Models "https://github.com/adarshmalviy/shadowid/blob/main/app/db/models.py"
    click Migrations "https://github.com/adarshmalviy/shadowid/blob/main/migrations/models/1_20240920191837_None.py"
    click Deps "https://github.com/adarshmalviy/shadowid/blob/main/pyproject.toml"

    %% Legend
    subgraph "Legend"
        direction LR
        A(("External Entity")):::external
        B["Code Module"]:::code
        C[(Datastore)]:::datastore
    end

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px,color:#000
    classDef code fill:#bbf,stroke:#333,stroke-width:1px,color:#000
    classDef datastore fill:#bfb,stroke:#333,stroke-width:1px,color:#000
```
