# taushifreza/go-social architecture

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

- Interactive diagram: https://gitdiagram.com/taushifreza/go-social
- Repository: https://github.com/taushifreza/go-social

## Overview

GoSocial is a REST social-network backend. A client request enters the API, passes shared middleware, and reaches user, post/feed, or comment handlers; those handlers use persistence and, for user profiles, a Redis cache. Registration also dispatches activation email, while authentication and role checks protect restricted operations. The README documents follow relationships, optimistic post updates, rate limiting, and runtime metrics. Wiring for several handlers and integrations is described but not present in the sampled source, so those links reflect documented behavior; uncertain implementation details are omitted.

Main entry points: [`cmd/api/main.go`](https://github.com/taushifreza/go-social/blob/main/cmd/api/main.go) (HTTP server), [`internal/store/storage.go`](https://github.com/taushifreza/go-social/blob/main/internal/store/storage.go) (Storage interfaces), [`cmd/api/users.go`](https://github.com/taushifreza/go-social/blob/main/cmd/api/users.go) (User handlers), [`internal/db/db.go`](https://github.com/taushifreza/go-social/blob/main/internal/db/db.go) (DB connection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_transport["API transport"]
  node_api["HTTP server<br/>[main.go]"]
  node_middleware["Middleware<br/>[middleware.go]"]
  node_json["JSON responses<br/>[json.go]"]
  node_metrics["Runtime metrics<br/>[main.go]"]
end

subgraph group_domain["Social features"]
  node_users["User handlers<br/>[users.go]"]
  node_posts["Post handlers<br/>[posts.go]"]
  node_feed["Feed handlers<br/>[feed.go]"]
  node_comments["Comment handlers<br/>[comments.go]"]
end

subgraph group_security["Security controls"]
  node_auth["JWT auth<br/>[auth.go]"]
  node_limiter["Rate limiter<br/>[fixed-window.go]"]
end

subgraph group_infra["Persistence and integrations"]
  node_store["Storage interfaces<br/>[storage.go]"]
  node_userstore["User repository<br/>[users.go]"]
  node_poststore["Post repository<br/>[posts.go]"]
  node_commentstore["Comment repository<br/>[comments.go]"]
  node_dbpool["DB connection<br/>[db.go]"]
  node_cache["Profile cache<br/>[users.go]"]
  node_mailer["Email sender<br/>[mailer.go]"]
  node_roles["Role repository<br/>[role.go]"]
end

node_client(("API client"))
node_postgres[("PostgreSQL")]
node_redis[("Redis")]
node_emailservice(("Email service"))

node_client -->|"sends requests"| node_api
node_api -->|"routes through"| node_middleware
node_middleware -->|"checks rate"| node_limiter
node_middleware -->|"verifies tokens"| node_auth
node_api -->|"dispatches users"| node_users
node_api -->|"dispatches posts"| node_posts
node_api -->|"dispatches feeds"| node_feed
node_api -->|"dispatches comments"| node_comments
node_users -->|"writes responses"| node_json
node_posts -->|"writes responses"| node_json
node_feed -->|"writes responses"| node_json
node_comments -->|"writes responses"| node_json
node_users -->|"uses storage"| node_store
node_posts -->|"uses storage"| node_store
node_feed -->|"loads feed"| node_store
node_comments -->|"uses storage"| node_store
node_store -->|"provides users"| node_userstore
node_store -->|"provides posts"| node_poststore
node_store -->|"provides comments"| node_commentstore
node_userstore -->|"queries"| node_dbpool
node_poststore -->|"queries"| node_dbpool
node_commentstore -->|"queries"| node_dbpool
node_roles -->|"queries"| node_dbpool
node_dbpool -->|"reads and writes"| node_postgres
node_users -->|"checks profile"| node_cache
node_cache -->|"reads and writes"| node_redis
node_users -->|"sends activation"| node_mailer
node_mailer -.->|"dispatches email"| node_emailservice
node_api -->|"publishes metrics"| node_metrics
node_auth -->|"issues tokens"| node_client
node_posts -->|"checks permissions"| node_roles

click node_api "https://github.com/taushifreza/go-social/blob/main/cmd/api/main.go"
click node_middleware "https://github.com/taushifreza/go-social/blob/main/cmd/api/middleware.go"
click node_users "https://github.com/taushifreza/go-social/blob/main/cmd/api/users.go"
click node_posts "https://github.com/taushifreza/go-social/blob/main/cmd/api/posts.go"
click node_feed "https://github.com/taushifreza/go-social/blob/main/cmd/api/feed.go"
click node_comments "https://github.com/taushifreza/go-social/blob/main/cmd/api/comments.go"
click node_json "https://github.com/taushifreza/go-social/blob/main/cmd/api/json.go"
click node_auth "https://github.com/taushifreza/go-social/blob/main/internal/auth/auth.go"
click node_limiter "https://github.com/taushifreza/go-social/blob/main/internal/ratelimiter/fixed-window.go"
click node_store "https://github.com/taushifreza/go-social/blob/main/internal/store/storage.go"
click node_userstore "https://github.com/taushifreza/go-social/blob/main/internal/store/users.go"
click node_poststore "https://github.com/taushifreza/go-social/blob/main/internal/store/posts.go"
click node_commentstore "https://github.com/taushifreza/go-social/blob/main/internal/store/comments.go"
click node_dbpool "https://github.com/taushifreza/go-social/blob/main/internal/db/db.go"
click node_cache "https://github.com/taushifreza/go-social/blob/main/internal/cache/users.go"
click node_mailer "https://github.com/taushifreza/go-social/blob/main/internal/mailer/mailer.go"
click node_metrics "https://github.com/taushifreza/go-social/blob/main/cmd/api/main.go"
click node_roles "https://github.com/taushifreza/go-social/blob/main/internal/store/role.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_api,node_middleware,node_json,node_metrics,node_client toneBlue
class node_users,node_posts,node_feed,node_comments,node_postgres,node_redis toneAmber
class node_auth,node_limiter toneMint
class node_store,node_userstore,node_poststore,node_commentstore,node_dbpool,node_cache,node_mailer,node_roles toneRose
class node_emailservice toneIndigo
```

## Components

### API transport

- [HTTP server](https://github.com/taushifreza/go-social/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [Middleware](https://github.com/taushifreza/go-social/blob/main/cmd/api/middleware.go): `cmd/api/middleware.go`
- [JSON responses](https://github.com/taushifreza/go-social/blob/main/cmd/api/json.go): `cmd/api/json.go`
- [Runtime metrics](https://github.com/taushifreza/go-social/blob/main/cmd/api/main.go): `cmd/api/main.go`

### Social features

- [User handlers](https://github.com/taushifreza/go-social/blob/main/cmd/api/users.go): `cmd/api/users.go`
- [Post handlers](https://github.com/taushifreza/go-social/blob/main/cmd/api/posts.go): `cmd/api/posts.go`
- [Feed handlers](https://github.com/taushifreza/go-social/blob/main/cmd/api/feed.go): `cmd/api/feed.go`
- [Comment handlers](https://github.com/taushifreza/go-social/blob/main/cmd/api/comments.go): `cmd/api/comments.go`

### Security controls

- [JWT auth](https://github.com/taushifreza/go-social/blob/main/internal/auth/auth.go): `internal/auth/auth.go`
- [Rate limiter](https://github.com/taushifreza/go-social/blob/main/internal/ratelimiter/fixed-window.go): `internal/ratelimiter/fixed-window.go`

### Persistence and integrations

- [Storage interfaces](https://github.com/taushifreza/go-social/blob/main/internal/store/storage.go): `internal/store/storage.go`
- [User repository](https://github.com/taushifreza/go-social/blob/main/internal/store/users.go): `internal/store/users.go`
- [Post repository](https://github.com/taushifreza/go-social/blob/main/internal/store/posts.go): `internal/store/posts.go`
- [Comment repository](https://github.com/taushifreza/go-social/blob/main/internal/store/comments.go): `internal/store/comments.go`
- [DB connection](https://github.com/taushifreza/go-social/blob/main/internal/db/db.go): `internal/db/db.go`
- [Profile cache](https://github.com/taushifreza/go-social/blob/main/internal/cache/users.go): `internal/cache/users.go`
- [Email sender](https://github.com/taushifreza/go-social/blob/main/internal/mailer/mailer.go): `internal/mailer/mailer.go`
- [Role repository](https://github.com/taushifreza/go-social/blob/main/internal/store/role.go): `internal/store/role.go`

### Other components

- **API client**
- **PostgreSQL**
- **Redis**
- **Email service**

## Connections

- API client → HTTP server: sends requests
- HTTP server → Middleware: routes through
- Middleware → Rate limiter: checks rate
- Middleware → JWT auth: verifies tokens
- HTTP server → User handlers: dispatches users
- HTTP server → Post handlers: dispatches posts
- HTTP server → Feed handlers: dispatches feeds
- HTTP server → Comment handlers: dispatches comments
- User handlers → JSON responses: writes responses
- Post handlers → JSON responses: writes responses
- Feed handlers → JSON responses: writes responses
- Comment handlers → JSON responses: writes responses
- User handlers → Storage interfaces: uses storage
- Post handlers → Storage interfaces: uses storage
- Feed handlers → Storage interfaces: loads feed
- Comment handlers → Storage interfaces: uses storage
- Storage interfaces → User repository: provides users
- Storage interfaces → Post repository: provides posts
- Storage interfaces → Comment repository: provides comments
- User repository → DB connection: queries
- Post repository → DB connection: queries
- Comment repository → DB connection: queries
- Role repository → DB connection: queries
- DB connection → PostgreSQL: reads and writes
- User handlers → Profile cache: checks profile
- Profile cache → Redis: reads and writes
- User handlers → Email sender: sends activation
- Email sender → Email service: dispatches email
- HTTP server → Runtime metrics: publishes metrics
- JWT auth → API client: issues tokens
- Post handlers → Role repository: checks permissions