# vdraha-dev/social-media-app architecture

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

- Interactive diagram: https://gitdiagram.com/vdraha-dev/social-media-app
- Repository: https://github.com/vdraha-dev/social-media-app

## Overview

#### 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`

Main entry points: [`app/identity/presentation/router.py`](https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/presentation/router.py) (Identity HTTP router), [`app/identity/application/use_cases.py`](https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/application/use_cases.py) (Identity use cases), [`compose.yaml`](https://github.com/vdraha-dev/social-media-app/blob/main/compose.yaml) (Container & Compose), [`app/main.py`](https://github.com/vdraha-dev/social-media-app/blob/main/app/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_container["Container &amp; Compose<br/>deployment<br/>[compose.yaml]"]
  node_fastapi["FastAPI application<br/>http application<br/>[main.py]"]
  node_postgres[("PostgreSQL 16<br/>external database")]
  node_alembic["Alembic migrations<br/>schema migration<br/>[env.py]"]
end

subgraph group_identity["Identity context"]
  node_identity_router["Identity HTTP router<br/>presentation<br/>[router.py]"]
  node_auth_dependencies["Auth dependencies<br/>presentation dependency<br/>[dependencies.py]"]
  node_identity_errors["Identity exception handlers<br/>error translation"]
  node_identity_use_cases["Identity use cases<br/>application layer<br/>[use_cases.py]"]
  node_identity_dto["Identity DTOs<br/>application contracts<br/>[dto.py]"]
  node_identity_domain{{"Identity domain model<br/>domain layer<br/>[entities.py]"}}
  node_identity_events["Identity domain events<br/>[events.py]"]
  node_security["JWT &amp; password security<br/>security adapter<br/>[security.py]"]
  node_identity_repository["Identity repository<br/>persistence adapter<br/>[repository.py]"]
  node_identity_models["Identity SQLAlchemy models<br/>persistence models<br/>[models.py]"]
end

subgraph group_profiles["Profiles context"]
  node_profiles_use_cases["Profile use cases<br/>application layer<br/>[use_cases.py]"]
  node_profile_contracts{{"Profile repository contracts<br/>domain contracts<br/>[repositories.py]"}}
  node_profiles_repository["Profile repository<br/>persistence adapter<br/>[repositories.py]"]
end

subgraph group_shared["Shared platform"]
  node_database[("Async database boundary<br/>database infrastructure<br/>[database.py]")]
  node_event_bus["In-memory event bus<br/>event mechanism<br/>[event_bus.py]"]
  node_shared_errors["Shared HTTP error handlers<br/>error translation"]
end

node_container -->|"runs"| node_fastapi
node_container -->|"provisions"| node_postgres
node_container -->|"runs migrations"| node_alembic
node_alembic -->|"updates schema"| node_postgres
node_fastapi -->|"mounts"| node_identity_router
node_fastapi -->|"registers"| node_shared_errors
node_identity_router -->|"uses"| node_auth_dependencies
node_identity_router -->|"maps requests to"| node_identity_dto
node_identity_router -->|"invokes"| node_identity_use_cases
node_identity_router -->|"translates failures"| node_identity_errors
node_auth_dependencies -->|"authenticates with"| node_security
node_identity_use_cases -->|"applies invariants"| node_identity_domain
node_identity_use_cases -->|"persists through"| node_identity_repository
node_identity_use_cases -->|"uses"| node_security
node_identity_domain -->|"emits"| node_identity_events
node_identity_events -->|"publishes via"| node_event_bus
node_identity_repository -->|"maps"| node_identity_models
node_identity_repository -->|"uses sessions"| node_database
node_database -->|"connects to"| node_postgres
node_profiles_use_cases -->|"depends on"| node_profile_contracts
node_profiles_use_cases -.->|"uses implementation"| node_profiles_repository
node_profiles_repository -->|"uses sessions"| node_database

click node_container "https://github.com/vdraha-dev/social-media-app/blob/main/compose.yaml"
click node_fastapi "https://github.com/vdraha-dev/social-media-app/blob/main/app/main.py"
click node_identity_router "https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/presentation/router.py"
click node_auth_dependencies "https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/presentation/dependencies.py"
click node_identity_errors "https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/presentation/exception_handlers.py"
click node_identity_use_cases "https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/application/use_cases.py"
click node_identity_dto "https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/application/dto.py"
click node_identity_domain "https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/domain/entities.py"
click node_identity_events "https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/domain/events.py"
click node_security "https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/infrastructure/security.py"
click node_identity_repository "https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/infrastructure/repository.py"
click node_identity_models "https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/infrastructure/models.py"
click node_profiles_use_cases "https://github.com/vdraha-dev/social-media-app/blob/main/app/profiles/application/use_cases.py"
click node_profile_contracts "https://github.com/vdraha-dev/social-media-app/blob/main/app/profiles/domain/repositories.py"
click node_profiles_repository "https://github.com/vdraha-dev/social-media-app/blob/main/app/profiles/infrastructure/repositories.py"
click node_database "https://github.com/vdraha-dev/social-media-app/blob/main/app/shared/infrastructure/database.py"
click node_event_bus "https://github.com/vdraha-dev/social-media-app/blob/main/app/shared/domain/event_bus.py"
click node_shared_errors "https://github.com/vdraha-dev/social-media-app/blob/main/app/shared/presentation/exception_handlers.py"
click node_alembic "https://github.com/vdraha-dev/social-media-app/blob/main/alembic/env.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_container,node_fastapi,node_postgres,node_alembic toneBlue
class node_identity_router,node_auth_dependencies,node_identity_errors,node_identity_use_cases,node_identity_dto,node_identity_domain,node_identity_events,node_security,node_identity_repository,node_identity_models toneAmber
class node_profiles_use_cases,node_profile_contracts,node_profiles_repository toneMint
class node_database,node_event_bus,node_shared_errors toneRose
```

## Components

### Runtime

- [Container & Compose](https://github.com/vdraha-dev/social-media-app/blob/main/compose.yaml): deployment · Runs the API, migrations, and PostgreSQL topology. · `compose.yaml`
- [FastAPI application](https://github.com/vdraha-dev/social-media-app/blob/main/app/main.py): http application · `app/main.py`
- **PostgreSQL 16**: external database
- [Alembic migrations](https://github.com/vdraha-dev/social-media-app/blob/main/alembic/env.py): schema migration · Maintains identity schema history. · `alembic/env.py`

### Identity context

- [Identity HTTP router](https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/presentation/router.py): presentation · Registration, login, logout, and current-user endpoints. · `app/identity/presentation/router.py`
- [Auth dependencies](https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/presentation/dependencies.py): presentation dependency · Resolves authenticated users and application services. · `app/identity/presentation/dependencies.py`
- [Identity exception handlers](https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/presentation/exception_handlers.py): error translation · `app/identity/presentation/exception_handlers.py`
- [Identity use cases](https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/application/use_cases.py): application layer · Orchestrates authentication and transaction work. · `app/identity/application/use_cases.py`
- [Identity DTOs](https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/application/dto.py): application contracts · `app/identity/application/dto.py`
- [Identity domain model](https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/domain/entities.py): domain layer · Entities and value objects enforce identity invariants. · `app/identity/domain/entities.py`
- [Identity domain events](https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/domain/events.py): domain events · `app/identity/domain/events.py`
- [JWT & password security](https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/infrastructure/security.py): security adapter · Hashes passwords and issues or validates JWTs. · `app/identity/infrastructure/security.py`
- [Identity repository](https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/infrastructure/repository.py): persistence adapter · Maps identity domain objects to storage records. · `app/identity/infrastructure/repository.py`
- [Identity SQLAlchemy models](https://github.com/vdraha-dev/social-media-app/blob/main/app/identity/infrastructure/models.py): persistence models · Includes identity and token-blacklist storage. · `app/identity/infrastructure/models.py`

### Profiles context

Parallel emerging bounded context.

- [Profile use cases](https://github.com/vdraha-dev/social-media-app/blob/main/app/profiles/application/use_cases.py): application layer · `app/profiles/application/use_cases.py`
- [Profile repository contracts](https://github.com/vdraha-dev/social-media-app/blob/main/app/profiles/domain/repositories.py): domain contracts · `app/profiles/domain/repositories.py`
- [Profile repository](https://github.com/vdraha-dev/social-media-app/blob/main/app/profiles/infrastructure/repositories.py): persistence adapter · `app/profiles/infrastructure/repositories.py`

### Shared platform

- [Async database boundary](https://github.com/vdraha-dev/social-media-app/blob/main/app/shared/infrastructure/database.py): database infrastructure · Owns SQLAlchemy async sessions and transactions. · `app/shared/infrastructure/database.py`
- [In-memory event bus](https://github.com/vdraha-dev/social-media-app/blob/main/app/shared/domain/event_bus.py): event mechanism · Delivers domain-event side effects within the process. · `app/shared/domain/event_bus.py`
- [Shared HTTP error handlers](https://github.com/vdraha-dev/social-media-app/blob/main/app/shared/presentation/exception_handlers.py): error translation · `app/shared/presentation/exception_handlers.py`

## Connections

- Container & Compose → FastAPI application: runs
- Container & Compose → PostgreSQL 16: provisions
- Container & Compose → Alembic migrations: runs migrations
- Alembic migrations → PostgreSQL 16: updates schema
- FastAPI application → Identity HTTP router: mounts
- FastAPI application → Shared HTTP error handlers: registers
- Identity HTTP router → Auth dependencies: uses
- Identity HTTP router → Identity DTOs: maps requests to
- Identity HTTP router → Identity use cases: invokes
- Identity HTTP router → Identity exception handlers: translates failures
- Auth dependencies → JWT & password security: authenticates with
- Identity use cases → Identity domain model: applies invariants
- Identity use cases → Identity repository: persists through
- Identity use cases → JWT & password security: uses
- Identity domain model → Identity domain events: emits
- Identity domain events → In-memory event bus: publishes via
- Identity repository → Identity SQLAlchemy models: maps
- Identity repository → Async database boundary: uses sessions
- Async database boundary → PostgreSQL 16: connects to
- Profile use cases → Profile repository contracts: depends on
- Profile use cases → Profile repository: uses implementation
- Profile repository → Async database boundary: uses sessions