How adarshmalviy/shadowid works
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