vdraha-dev/social-media-app

Purpose and Entry Points

This is an async FastAPI monolith for social-media identity/access management: registration, JWT login, logout via token invalidation, and current-user lookup. The HTTP application is created in app/main.py; API composition and identity endpoints reside in app/identity/presentation/router.py. It runs under Uvicorn directly or through Dockerfile and compose.yaml.

Bounded Contexts and Layering

The repository is organized as DDD-style bounded contexts. Identity is the implemented authentication context; Profiles is a parallel/emerging context with the same domain/application/infrastructure/presentation split. Shared code supplies cross-context primitives and infrastructure.

• Identity: app/identity/domain/entities.py, app/identity/application/use_cases.py, app/identity/infrastructure/repository.py

• Profiles: app/profiles/domain/entities.py, app/profiles/application/use_cases.py, app/profiles/infrastructure/repositories.py

• Shared: app/shared/domain/base_entity.py, app/shared/infrastructure/database.py

Request and Control Flow

Requests enter FastAPI routers, where presentation dependencies resolve authentication and application services. Router handlers map HTTP/Pydantic inputs to DTOs and invoke use cases; exception handlers translate domain/application failures into HTTP responses.

• HTTP boundary: app/identity/presentation/router.py, app/identity/presentation/dependencies.py, app/identity/presentation/exception_handlers.py

• Application orchestration: app/identity/application/dto.py, app/identity/application/use_cases.py

• Cross-cutting HTTP errors: app/shared/presentation/exception_handlers.py

Domain Model and Events

Business invariants belong in entities and immutable value objects, insulated from FastAPI and SQLAlchemy. Identity emits domain events; the shared in-memory event bus enables decoupled side effects within the process. Domain repository abstractions prevent use cases from depending on persistence implementation.

• Domain: app/identity/domain/entities.py, app/identity/domain/value_objects.py, app/identity/domain/events.py

• Shared event mechanism: app/shared/domain/event_bus.py

• Profile contracts: app/profiles/domain/repositories.py

Persistence and Transactions

PostgreSQL is accessed asynchronously through SQLAlchemy 2.x and asyncpg. Shared database infrastructure owns session/transaction setup; context-specific SQLAlchemy models and repositories map between persistence records and domain objects. The Unit of Work boundary is exercised by application use cases/repositories rather than exposed to presentation.

• Database boundary: app/shared/infrastructure/database.py

• Identity persistence: app/identity/infrastructure/models.py, app/identity/infrastructure/repository.py

• Profile persistence: app/profiles/infrastructure/models.py, app/profiles/infrastructure/repositories.py

Authentication and Security

Identity infrastructure owns password hashing and JWT issuance/validation, keeping cryptographic details outside domain logic. Presentation dependencies use these services to authenticate protected requests; logout persists or otherwise records token-blacklisting state through identity persistence.

• Security adapter: app/identity/infrastructure/security.py

• Auth wiring: app/identity/presentation/dependencies.py

• Identity storage models: app/identity/infrastructure/models.py

Runtime and Schema Operations

Configuration is environment-driven, including async runtime and synchronous migration database URLs plus JWT secret. PostgreSQL 16 is the material external service. Alembic maintains schema history, including identity tables and token-expiry fixes; Compose provides application, migration, test, debug, and database service topology.

• Settings: app/shared/config.py

• Migration environment/history: alembic/env.py, alembic/versions/bea8099fe81f_init.py, alembic/versions/f8640513a824_add_identity_tables.py

• Deployment topology: compose.yaml, Dockerfile