# inwerejosic/actix-blog-api architecture

> Architecture diagram of the GitHub repository inwerejosic/actix-blog-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/inwerejosic/actix-blog-api
- Repository: https://github.com/inwerejosic/actix-blog-api

## Overview

#### Purpose and entry point
Rust REST API for a blog platform. It exposes session-authenticated user, post, tag, and post–tag relationship endpoints over HTTP. Application startup, dependency initialization, middleware, and route registration are centered in `src/main.rs`.

#### HTTP/API layer
Actix-web handlers implement login/logout/current-user flows plus CRUD-oriented user, post, and tag operations. Handlers receive request data, enforce endpoint-level behavior, invoke persistence operations, and translate failures into HTTP responses.
- `src/handlers.rs`
- `src/main.rs`
- `src/error.rs`

#### Authentication and session boundary
Authentication uses bcrypt-backed password verification and cookie sessions. Session state is persisted in Redis rather than process memory, making authenticated requests depend on both the signed session cookie/secret and Redis availability. Protected operations such as `/me` resolve the authenticated user through this boundary.
- `src/auth.rs`
- `src/handlers.rs`
- `src/main.rs`

#### Persistence and schema lifecycle
PostgreSQL is the system of record for users, blog posts, tags, the `blog_tag` junction, and schema-defined comments. SQLx manages database access; startup creates or prepares the schema automatically. The database module is the persistence boundary shared by HTTP handlers.
- `src/db.rs`
- `src/models.rs`
- `src/main.rs`

#### Domain model and relationships
Typed request/response and database-facing entities represent users, posts, tags, and authentication payloads. Posts belong to users; tags attach to posts through a many-to-many junction. Post retrieval includes its tags, while attachment and detachment mutate the relation.
- `src/models.rs`
- `src/handlers.rs`
- `src/db.rs`

#### Error propagation
Application-specific errors centralize conversion of authentication, validation, database, and missing-resource failures into API responses. This keeps handlers focused on request orchestration while preserving consistent failure semantics.
- `src/error.rs`
- `src/handlers.rs`

#### Runtime and deployment topology
The API runs as a Rust/Actix process on port 8080, requiring `DATABASE_URL`, `REDIS_URL`, and `SECRET_KEY`. Docker Compose provisions API, PostgreSQL 16, and Redis 7 with persistent volumes. The Docker image is built from `Dockerfile`; GitHub Actions publishes it to GHCR and Docker Hub.
- `Dockerfile`
- `docker-compose.yaml`
- `.github/workflows/docker-publish.yaml`
- `src/main.rs`

Main entry points: [`src/handlers.rs`](https://github.com/inwerejosic/actix-blog-api/blob/main/src/handlers.rs) (Endpoint handlers), [`src/main.rs`](https://github.com/inwerejosic/actix-blog-api/blob/main/src/main.rs) (Actix application), [`src/db.rs`](https://github.com/inwerejosic/actix-blog-api/blob/main/src/db.rs) (Database module), [`docker-compose.yaml`](https://github.com/inwerejosic/actix-blog-api/blob/main/docker-compose.yaml) (Docker Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_main["Actix application<br/>startup and routing<br/>[main.rs]"]
  node_handlers["Endpoint handlers<br/>Actix handlers<br/>[handlers.rs]"]
  node_errors["API error mapping<br/>error boundary<br/>[error.rs]"]
end

subgraph group_core["Application Core"]
  node_auth["Authentication<br/>bcrypt and sessions<br/>[auth.rs]"]
  node_models["Domain models<br/>typed entities<br/>[models.rs]"]
  node_db["Database module<br/>SQLx persistence<br/>[db.rs]"]
end

subgraph group_data["Stateful Services"]
  node_postgres[("PostgreSQL 16<br/>system of record")]
  node_redis[("Redis 7<br/>session store")]
end

subgraph group_delivery["Build &amp; Deployment"]
  node_compose["Docker Compose<br/>local runtime topology"]
  node_image["API container image<br/>Docker image"]
  node_publish["Image publishing<br/>GitHub Actions workflow"]
end

node_client(("API clients<br/>HTTP consumer"))

node_client -->|"HTTP requests"| node_main
node_main -->|"registers routes"| node_handlers
node_main -->|"configures sessions"| node_auth
node_main -->|"initializes pool and schema"| node_db
node_handlers -->|"login and protected identity"| node_auth
node_handlers -->|"CRUD and tag relations"| node_db
node_handlers -->|"uses payloads and entities"| node_models
node_handlers -->|"maps failures"| node_errors
node_auth -->|"reads and writes session state"| node_redis
node_db -->|"SQLx queries and schema"| node_postgres
node_db -->|"hydrates entities"| node_models
node_compose -->|"runs API image"| node_image
node_compose -->|"provisions"| node_postgres
node_compose -->|"provisions"| node_redis
node_publish -->|"builds and publishes"| node_image

click node_main "https://github.com/inwerejosic/actix-blog-api/blob/main/src/main.rs"
click node_handlers "https://github.com/inwerejosic/actix-blog-api/blob/main/src/handlers.rs"
click node_errors "https://github.com/inwerejosic/actix-blog-api/blob/main/src/error.rs"
click node_auth "https://github.com/inwerejosic/actix-blog-api/blob/main/src/auth.rs"
click node_models "https://github.com/inwerejosic/actix-blog-api/blob/main/src/models.rs"
click node_db "https://github.com/inwerejosic/actix-blog-api/blob/main/src/db.rs"
click node_postgres "https://github.com/inwerejosic/actix-blog-api/blob/main/docker-compose.yaml"
click node_redis "https://github.com/inwerejosic/actix-blog-api/blob/main/docker-compose.yaml"
click node_compose "https://github.com/inwerejosic/actix-blog-api/blob/main/docker-compose.yaml"
click node_image "https://github.com/inwerejosic/actix-blog-api/blob/main/Dockerfile"
click node_publish "https://github.com/inwerejosic/actix-blog-api/blob/main/.github/workflows/docker-publish.yaml"

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_main,node_handlers,node_errors toneBlue
class node_auth,node_models,node_db toneAmber
class node_postgres,node_redis toneMint
class node_compose,node_image,node_publish toneRose
class node_client toneNeutral
```

## Components

### HTTP API

- [Actix application](https://github.com/inwerejosic/actix-blog-api/blob/main/src/main.rs): startup and routing · Initializes dependencies, middleware, and routes on port 8080. · `src/main.rs`
- [Endpoint handlers](https://github.com/inwerejosic/actix-blog-api/blob/main/src/handlers.rs): Actix handlers · Implements session, user, post, tag, and relationship endpoints. · `src/handlers.rs`
- [API error mapping](https://github.com/inwerejosic/actix-blog-api/blob/main/src/error.rs): error boundary · Converts application failures into consistent HTTP responses. · `src/error.rs`

### Application Core

- [Authentication](https://github.com/inwerejosic/actix-blog-api/blob/main/src/auth.rs): bcrypt and sessions · Verifies passwords and resolves authenticated users from sessions. · `src/auth.rs`
- [Domain models](https://github.com/inwerejosic/actix-blog-api/blob/main/src/models.rs): typed entities · Defines users, posts, tags, auth payloads, and request/response types. · `src/models.rs`
- [Database module](https://github.com/inwerejosic/actix-blog-api/blob/main/src/db.rs): SQLx persistence · Shared persistence boundary and schema preparation logic. · `src/db.rs`

### Stateful Services

- [PostgreSQL 16](https://github.com/inwerejosic/actix-blog-api/blob/main/docker-compose.yaml): system of record · Stores users, posts, tags, blog_tag relations, and comments. · `docker-compose.yaml`
- [Redis 7](https://github.com/inwerejosic/actix-blog-api/blob/main/docker-compose.yaml): session store · Persists cookie-session state outside the API process. · `docker-compose.yaml`

### Build & Deployment

- [Docker Compose](https://github.com/inwerejosic/actix-blog-api/blob/main/docker-compose.yaml): local runtime topology · Provisions the API, PostgreSQL, Redis, and persistent volumes. · `docker-compose.yaml`
- [API container image](https://github.com/inwerejosic/actix-blog-api/blob/main/Dockerfile): Docker image · Builds the Rust API runtime image. · `Dockerfile`
- [Image publishing](https://github.com/inwerejosic/actix-blog-api/blob/main/.github/workflows/docker-publish.yaml): GitHub Actions workflow · Publishes the container image to GHCR and Docker Hub. · `.github/workflows/docker-publish.yaml`

### Other components

- **API clients**: HTTP consumer

## Connections

- API clients → Actix application: HTTP requests
- Actix application → Endpoint handlers: registers routes
- Actix application → Authentication: configures sessions
- Actix application → Database module: initializes pool and schema
- Endpoint handlers → Authentication: login and protected identity
- Endpoint handlers → Database module: CRUD and tag relations
- Endpoint handlers → Domain models: uses payloads and entities
- Endpoint handlers → API error mapping: maps failures
- Authentication → Redis 7: reads and writes session state
- Database module → PostgreSQL 16: SQLx queries and schema
- Database module → Domain models: hydrates entities
- Docker Compose → API container image: runs API image
- Docker Compose → PostgreSQL 16: provisions
- Docker Compose → Redis 7: provisions
- Image publishing → API container image: builds and publishes