# vortexpluz/chirpy architecture

> Architecture diagram of the GitHub repository vortexpluz/chirpy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vortexpluz/chirpy
- Repository: https://github.com/vortexpluz/chirpy

## Overview

Chirpy is a small HTTP microblogging API: users register and log in, manage bearer/refresh tokens, and create, list, retrieve, or delete short posts (“chirps”); a Polka webhook can grant Chirpy Red status. The main mux dispatches requests to handlers, which use authentication helpers and SQL-backed query modules. The tree and sampled code support the API, persistence, static app serving, and webhook integration; details of unsampled handlers and middleware are limited.

Main entry points: [`main.go`](https://github.com/vortexpluz/chirpy/blob/main/main.go) (HTTP Mux), [`handler_users.go`](https://github.com/vortexpluz/chirpy/blob/main/handler_users.go) (User Handlers), [`handler_tokens.go`](https://github.com/vortexpluz/chirpy/blob/main/handler_tokens.go) (Token Handlers), [`handler_chirps.go`](https://github.com/vortexpluz/chirpy/blob/main/handler_chirps.go) (Chirp Handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_server["HTTP Mux<br/>[main.go]"]
  node_static["Static App<br/>[main.go]"]
  node_health["Health Endpoint<br/>[main.go]"]
  node_admin["Admin Endpoints<br/>[handler_admin.go]"]
  node_webhook["Upgrade Webhook"]
end

subgraph group_identity["Identity And Access"]
  node_users["User Handlers<br/>[handler_users.go]"]
  node_token_handlers["Token Handlers<br/>[handler_tokens.go]"]
  node_auth_tokens["Bearer And Refresh<br/>[tokens.go]"]
  node_auth_jwt["JWT Auth<br/>[jwt.go]"]
  node_auth_pass["Password Hashing<br/>[pass.go]"]
  node_auth_key["API Key Auth<br/>[api_key.go]"]
end

subgraph group_chirps["Chirp Content"]
  node_chirp_handlers["Chirp Handlers<br/>[handler_chirps.go]"]
end

subgraph group_storage["Persistence"]
  node_db_init["Query Setup<br/>[db.go]"]
  node_user_queries["User Queries<br/>[users.sql.go]"]
  node_chirp_queries["Chirp Queries<br/>[chirps.sql.go]"]
  node_token_queries["Refresh Queries<br/>[tokens.sql.go]"]
  node_postgres[("PostgreSQL")]
end

node_client(("API Client"))
node_polka(("Polka Service"))

node_client -->|"sends requests"| node_server
node_polka -.->|"sends webhook"| node_server
node_server -->|"serves files"| node_static
node_server -->|"dispatches health"| node_health
node_server -->|"dispatches user routes"| node_users
node_server -->|"dispatches token routes"| node_token_handlers
node_server -->|"dispatches chirp routes"| node_chirp_handlers
node_server -->|"dispatches webhook"| node_webhook
node_server -->|"dispatches admin"| node_admin
node_server -->|"initializes queries"| node_db_init
node_users -->|"hashes passwords"| node_auth_pass
node_users -->|"reads bearer token"| node_auth_tokens
node_users -->|"issues and validates JWT"| node_auth_jwt
node_users -->|"reads and writes users"| node_user_queries
node_users -->|"creates refresh token"| node_token_queries
node_token_handlers -->|"reads bearer token"| node_auth_tokens
node_token_handlers -->|"issues JWT"| node_auth_jwt
node_token_handlers -->|"reads and revokes tokens"| node_token_queries
node_chirp_handlers -->|"reads bearer token"| node_auth_tokens
node_chirp_handlers -->|"validates JWT"| node_auth_jwt
node_chirp_handlers -->|"reads and writes chirps"| node_chirp_queries
node_webhook -->|"checks API key"| node_auth_key
node_webhook -->|"upgrades user"| node_user_queries
node_admin -->|"truncates users"| node_user_queries
node_db_init -->|"opens connection"| node_postgres
node_user_queries -->|"executes SQL"| node_postgres
node_chirp_queries -->|"executes SQL"| node_postgres
node_token_queries -->|"executes SQL"| node_postgres

click node_server "https://github.com/vortexpluz/chirpy/blob/main/main.go"
click node_static "https://github.com/vortexpluz/chirpy/blob/main/main.go"
click node_health "https://github.com/vortexpluz/chirpy/blob/main/main.go"
click node_admin "https://github.com/vortexpluz/chirpy/blob/main/handler_admin.go"
click node_users "https://github.com/vortexpluz/chirpy/blob/main/handler_users.go"
click node_token_handlers "https://github.com/vortexpluz/chirpy/blob/main/handler_tokens.go"
click node_auth_tokens "https://github.com/vortexpluz/chirpy/blob/main/internal/auth/tokens.go"
click node_auth_jwt "https://github.com/vortexpluz/chirpy/blob/main/internal/auth/jwt.go"
click node_auth_pass "https://github.com/vortexpluz/chirpy/blob/main/internal/auth/pass.go"
click node_auth_key "https://github.com/vortexpluz/chirpy/blob/main/internal/auth/api_key.go"
click node_chirp_handlers "https://github.com/vortexpluz/chirpy/blob/main/handler_chirps.go"
click node_webhook "https://github.com/vortexpluz/chirpy/blob/main/handler_weebhooks.go"
click node_db_init "https://github.com/vortexpluz/chirpy/blob/main/internal/database/db.go"
click node_user_queries "https://github.com/vortexpluz/chirpy/blob/main/internal/database/users.sql.go"
click node_chirp_queries "https://github.com/vortexpluz/chirpy/blob/main/internal/database/chirps.sql.go"
click node_token_queries "https://github.com/vortexpluz/chirpy/blob/main/internal/database/tokens.sql.go"

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_server,node_static,node_health,node_admin,node_webhook,node_client toneBlue
class node_users,node_token_handlers,node_auth_tokens,node_auth_jwt,node_auth_pass,node_auth_key toneAmber
class node_chirp_handlers toneMint
class node_db_init,node_user_queries,node_chirp_queries,node_token_queries,node_postgres toneRose
class node_polka toneIndigo
```

## Components

### HTTP API

- [HTTP Mux](https://github.com/vortexpluz/chirpy/blob/main/main.go): `main.go`
- [Static App](https://github.com/vortexpluz/chirpy/blob/main/main.go): `main.go`
- [Health Endpoint](https://github.com/vortexpluz/chirpy/blob/main/main.go): `main.go`
- [Admin Endpoints](https://github.com/vortexpluz/chirpy/blob/main/handler_admin.go): `handler_admin.go`
- [Upgrade Webhook](https://github.com/vortexpluz/chirpy/blob/main/handler_weebhooks.go): `handler_weebhooks.go`

### Identity And Access

- [User Handlers](https://github.com/vortexpluz/chirpy/blob/main/handler_users.go): `handler_users.go`
- [Token Handlers](https://github.com/vortexpluz/chirpy/blob/main/handler_tokens.go): `handler_tokens.go`
- [Bearer And Refresh](https://github.com/vortexpluz/chirpy/blob/main/internal/auth/tokens.go): `internal/auth/tokens.go`
- [JWT Auth](https://github.com/vortexpluz/chirpy/blob/main/internal/auth/jwt.go): `internal/auth/jwt.go`
- [Password Hashing](https://github.com/vortexpluz/chirpy/blob/main/internal/auth/pass.go): `internal/auth/pass.go`
- [API Key Auth](https://github.com/vortexpluz/chirpy/blob/main/internal/auth/api_key.go): `internal/auth/api_key.go`

### Chirp Content

- [Chirp Handlers](https://github.com/vortexpluz/chirpy/blob/main/handler_chirps.go): `handler_chirps.go`

### Persistence

- [Query Setup](https://github.com/vortexpluz/chirpy/blob/main/internal/database/db.go): `internal/database/db.go`
- [User Queries](https://github.com/vortexpluz/chirpy/blob/main/internal/database/users.sql.go): `internal/database/users.sql.go`
- [Chirp Queries](https://github.com/vortexpluz/chirpy/blob/main/internal/database/chirps.sql.go): `internal/database/chirps.sql.go`
- [Refresh Queries](https://github.com/vortexpluz/chirpy/blob/main/internal/database/tokens.sql.go): `internal/database/tokens.sql.go`
- **PostgreSQL**

### Other components

- **API Client**
- **Polka Service**

## Connections

- API Client → HTTP Mux: sends requests
- Polka Service → HTTP Mux: sends webhook
- HTTP Mux → Static App: serves files
- HTTP Mux → Health Endpoint: dispatches health
- HTTP Mux → User Handlers: dispatches user routes
- HTTP Mux → Token Handlers: dispatches token routes
- HTTP Mux → Chirp Handlers: dispatches chirp routes
- HTTP Mux → Upgrade Webhook: dispatches webhook
- HTTP Mux → Admin Endpoints: dispatches admin
- HTTP Mux → Query Setup: initializes queries
- User Handlers → Password Hashing: hashes passwords
- User Handlers → Bearer And Refresh: reads bearer token
- User Handlers → JWT Auth: issues and validates JWT
- User Handlers → User Queries: reads and writes users
- User Handlers → Refresh Queries: creates refresh token
- Token Handlers → Bearer And Refresh: reads bearer token
- Token Handlers → JWT Auth: issues JWT
- Token Handlers → Refresh Queries: reads and revokes tokens
- Chirp Handlers → Bearer And Refresh: reads bearer token
- Chirp Handlers → JWT Auth: validates JWT
- Chirp Handlers → Chirp Queries: reads and writes chirps
- Upgrade Webhook → API Key Auth: checks API key
- Upgrade Webhook → User Queries: upgrades user
- Admin Endpoints → User Queries: truncates users
- Query Setup → PostgreSQL: opens connection
- User Queries → PostgreSQL: executes SQL
- Chirp Queries → PostgreSQL: executes SQL
- Refresh Queries → PostgreSQL: executes SQL