# kwasos/gator architecture

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

- Interactive diagram: https://gitdiagram.com/kwasos/gator
- Repository: https://github.com/kwasos/gator

## Overview

Gator is a terminal RSS aggregator: users register or log in, manage feeds and follows, the periodic aggregator fetches feeds and stores posts, and browse displays recent posts from followed feeds. The command router in main.go dispatches CLI commands to handlers; handlers own database operations through sqlc-generated queries. README capabilities are represented, but RSS parsing and config are only sampled in part, so uncertain internal details are omitted.

Main entry points: [`internal/database/db.go`](https://github.com/kwasos/gator/blob/main/internal/database/db.go) (Query API), [`main.go`](https://github.com/kwasos/gator/blob/main/main.go) (Command router), [`commands.go`](https://github.com/kwasos/gator/blob/main/commands.go) (User commands), [`handler_agg.go`](https://github.com/kwasos/gator/blob/main/handler_agg.go) (Periodic aggregator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_router["Command router<br/>[main.go]"]
  node_commands["User commands<br/>[commands.go]"]
  node_feed_commands["Feed commands<br/>[handler_feed.go]"]
  node_browse["Browse posts<br/>[handler_browse.go]"]
  node_config["User config<br/>[config.go]"]
end

subgraph group_feeds["Feed collection"]
  node_aggregator["Periodic aggregator<br/>[handler_agg.go]"]
  node_rss["RSS fetch<br/>[rss_feed.go]"]
end

subgraph group_storage["Persistence"]
  node_query_api["Query API<br/>[db.go]"]
  node_user_queries["User queries<br/>[users.sql.go]"]
  node_feed_queries["Feed queries<br/>[feeds.sql.go]"]
  node_follow_queries["Follow queries<br/>[feed_follow.sql.go]"]
  node_post_queries["Post queries<br/>[posts.sql.go]"]
end

node_user(("CLI user"))
node_postgres[("PostgreSQL")]
node_rss_service["RSS sources"]

node_user -->|"runs commands"| node_router
node_router -->|"dispatches"| node_commands
node_router -->|"dispatches"| node_feed_commands
node_router -->|"dispatches"| node_browse
node_router -->|"dispatches"| node_aggregator
node_router -->|"reads config"| node_config
node_commands -->|"sets user"| node_config
node_commands -->|"calls queries"| node_query_api
node_feed_commands -->|"calls queries"| node_query_api
node_browse -->|"calls queries"| node_query_api
node_aggregator -->|"calls queries"| node_query_api
node_aggregator -->|"fetches feed"| node_rss
node_rss -->|"requests RSS"| node_rss_service
node_query_api -->|"uses"| node_user_queries
node_query_api -->|"uses"| node_feed_queries
node_query_api -->|"uses"| node_follow_queries
node_query_api -->|"uses"| node_post_queries
node_user_queries -->|"reads/writes"| node_postgres
node_feed_queries -->|"reads/writes"| node_postgres
node_follow_queries -->|"reads/writes"| node_postgres
node_post_queries -->|"reads/writes"| node_postgres

click node_router "https://github.com/kwasos/gator/blob/main/main.go"
click node_commands "https://github.com/kwasos/gator/blob/main/commands.go"
click node_feed_commands "https://github.com/kwasos/gator/blob/main/handler_feed.go"
click node_browse "https://github.com/kwasos/gator/blob/main/handler_browse.go"
click node_config "https://github.com/kwasos/gator/blob/main/internal/config/config.go"
click node_aggregator "https://github.com/kwasos/gator/blob/main/handler_agg.go"
click node_rss "https://github.com/kwasos/gator/blob/main/rss_feed.go"
click node_query_api "https://github.com/kwasos/gator/blob/main/internal/database/db.go"
click node_user_queries "https://github.com/kwasos/gator/blob/main/internal/database/users.sql.go"
click node_feed_queries "https://github.com/kwasos/gator/blob/main/internal/database/feeds.sql.go"
click node_follow_queries "https://github.com/kwasos/gator/blob/main/internal/database/feed_follow.sql.go"
click node_post_queries "https://github.com/kwasos/gator/blob/main/internal/database/posts.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_router,node_commands,node_feed_commands,node_browse,node_config,node_user toneBlue
class node_aggregator,node_rss,node_postgres toneAmber
class node_query_api,node_user_queries,node_feed_queries,node_follow_queries,node_post_queries toneMint
class node_rss_service toneIndigo
```

## Components

### CLI workflow

- [Command router](https://github.com/kwasos/gator/blob/main/main.go): `main.go`
- [User commands](https://github.com/kwasos/gator/blob/main/commands.go): `commands.go`
- [Feed commands](https://github.com/kwasos/gator/blob/main/handler_feed.go): `handler_feed.go`
- [Browse posts](https://github.com/kwasos/gator/blob/main/handler_browse.go): `handler_browse.go`
- [User config](https://github.com/kwasos/gator/blob/main/internal/config/config.go): `internal/config/config.go`

### Feed collection

- [Periodic aggregator](https://github.com/kwasos/gator/blob/main/handler_agg.go): `handler_agg.go`
- [RSS fetch](https://github.com/kwasos/gator/blob/main/rss_feed.go): `rss_feed.go`

### Persistence

- [Query API](https://github.com/kwasos/gator/blob/main/internal/database/db.go): `internal/database/db.go`
- [User queries](https://github.com/kwasos/gator/blob/main/internal/database/users.sql.go): `internal/database/users.sql.go`
- [Feed queries](https://github.com/kwasos/gator/blob/main/internal/database/feeds.sql.go): `internal/database/feeds.sql.go`
- [Follow queries](https://github.com/kwasos/gator/blob/main/internal/database/feed_follow.sql.go): `internal/database/feed_follow.sql.go`
- [Post queries](https://github.com/kwasos/gator/blob/main/internal/database/posts.sql.go): `internal/database/posts.sql.go`

### Other components

- **CLI user**
- **PostgreSQL**
- **RSS sources**

## Connections

- CLI user → Command router: runs commands
- Command router → User commands: dispatches
- Command router → Feed commands: dispatches
- Command router → Browse posts: dispatches
- Command router → Periodic aggregator: dispatches
- Command router → User config: reads config
- User commands → User config: sets user
- User commands → Query API: calls queries
- Feed commands → Query API: calls queries
- Browse posts → Query API: calls queries
- Periodic aggregator → Query API: calls queries
- Periodic aggregator → RSS fetch: fetches feed
- RSS fetch → RSS sources: requests RSS
- Query API → User queries: uses
- Query API → Feed queries: uses
- Query API → Follow queries: uses
- Query API → Post queries: uses
- User queries → PostgreSQL: reads/writes
- Feed queries → PostgreSQL: reads/writes
- Follow queries → PostgreSQL: reads/writes
- Post queries → PostgreSQL: reads/writes