# keepo-dot/gator architecture

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

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

## Overview

Gator is a command-line RSS feed manager: users register or log in, add feeds, follow or unfollow feeds, and list users and feeds. The CLI dispatches commands to handlers, which use configuration and PostgreSQL-backed data access. RSS fetching and parsing are present, but the sampled source does not establish how aggregation invokes them; that connection is left out.

Main entry points: [`commands.go`](https://github.com/keepo-dot/gator/blob/main/commands.go) (Command dispatch), [`internal/database`](https://github.com/keepo-dot/gator/tree/main/internal/database) (Database queries), [`main.go`](https://github.com/keepo-dot/gator/blob/main/main.go) (Startup), [`internal/config/config.go`](https://github.com/keepo-dot/gator/blob/main/internal/config/config.go) (User config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI runtime"]
  node_main["Startup<br/>[main.go]"]
  node_commands["Command dispatch<br/>[commands.go]"]
  node_state["Shared state<br/>[state.go]"]
  node_middleware["Login middleware<br/>[mw_logged_in.go]"]
end

subgraph group_identity["Users and config"]
  node_user_handlers["User commands<br/>[handler_user.go]"]
  node_register["Registration"]
  node_reset["Reset users<br/>[handler_reset.go]"]
  node_config["User config<br/>[config.go]"]
  node_config_file["Config file"]
end

subgraph group_feeds["Feed management"]
  node_feed_handlers["Feed commands<br/>[handler_feeds.go]"]
  node_add_feed["Add feed<br/>[handler_rss.go]"]
  node_follow["Follow feed<br/>[handler_follow.go]"]
  node_following["List follows"]
  node_unfollow["Unfollow feed"]
  node_aggregation["Feed aggregation<br/>[handler_agg.go]"]
  node_rss["RSS fetch and parse<br/>[handler_rss.go]"]
end

subgraph group_storage["Persistence"]
  node_db_access["Database queries"]
  node_postgres[("PostgreSQL")]
end

node_user(("CLI user"))
node_rss_service(("RSS sources"))

node_user -->|"runs command"| node_main
node_main -->|"reads config"| node_config
node_main -->|"opens database"| node_db_access
node_main -->|"builds state"| node_state
node_main -->|"runs dispatch"| node_commands
node_commands -->|"wraps commands"| node_middleware
node_commands -->|"dispatches"| node_user_handlers
node_commands -->|"dispatches"| node_register
node_commands -->|"dispatches"| node_reset
node_commands -->|"dispatches"| node_feed_handlers
node_commands -->|"dispatches"| node_add_feed
node_commands -->|"dispatches"| node_follow
node_commands -->|"dispatches"| node_following
node_commands -->|"dispatches"| node_unfollow
node_commands -->|"dispatches"| node_aggregation
node_user_handlers -->|"queries users"| node_db_access
node_user_handlers -->|"sets current user"| node_config
node_register -->|"creates user"| node_db_access
node_register -->|"sets current user"| node_config
node_reset -->|"resets users"| node_db_access
node_feed_handlers -->|"lists feeds"| node_db_access
node_add_feed -->|"saves feed and follow"| node_db_access
node_follow -->|"creates follow"| node_db_access
node_following -->|"lists follows"| node_db_access
node_unfollow -->|"deletes follow"| node_db_access
node_db_access -->|"queries"| node_postgres
node_config -->|"reads and writes"| node_config_file
node_rss -.->|"fetches RSS"| node_rss_service

click node_main "https://github.com/keepo-dot/gator/blob/main/main.go"
click node_commands "https://github.com/keepo-dot/gator/blob/main/commands.go"
click node_state "https://github.com/keepo-dot/gator/blob/main/state.go"
click node_middleware "https://github.com/keepo-dot/gator/blob/main/mw_logged_in.go"
click node_user_handlers "https://github.com/keepo-dot/gator/blob/main/handler_user.go"
click node_register "https://github.com/keepo-dot/gator/blob/main/handler_register.go"
click node_reset "https://github.com/keepo-dot/gator/blob/main/handler_reset.go"
click node_config "https://github.com/keepo-dot/gator/blob/main/internal/config/config.go"
click node_feed_handlers "https://github.com/keepo-dot/gator/blob/main/handler_feeds.go"
click node_add_feed "https://github.com/keepo-dot/gator/blob/main/handler_rss.go"
click node_follow "https://github.com/keepo-dot/gator/blob/main/handler_follow.go"
click node_following "https://github.com/keepo-dot/gator/blob/main/handler_following.go"
click node_unfollow "https://github.com/keepo-dot/gator/blob/main/handler_unfollow.go"
click node_aggregation "https://github.com/keepo-dot/gator/blob/main/handler_agg.go"
click node_rss "https://github.com/keepo-dot/gator/blob/main/handler_rss.go"
click node_db_access "https://github.com/keepo-dot/gator/tree/main/internal/database"

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_commands,node_state,node_middleware,node_user toneBlue
class node_user_handlers,node_register,node_reset,node_config,node_config_file toneAmber
class node_feed_handlers,node_add_feed,node_follow,node_following,node_unfollow,node_aggregation,node_rss toneMint
class node_db_access,node_postgres toneRose
class node_rss_service toneIndigo
```

## Components

### CLI runtime

- [Startup](https://github.com/keepo-dot/gator/blob/main/main.go): `main.go`
- [Command dispatch](https://github.com/keepo-dot/gator/blob/main/commands.go): `commands.go`
- [Shared state](https://github.com/keepo-dot/gator/blob/main/state.go): `state.go`
- [Login middleware](https://github.com/keepo-dot/gator/blob/main/mw_logged_in.go): `mw_logged_in.go`

### Users and config

- [User commands](https://github.com/keepo-dot/gator/blob/main/handler_user.go): `handler_user.go`
- [Registration](https://github.com/keepo-dot/gator/blob/main/handler_register.go): `handler_register.go`
- [Reset users](https://github.com/keepo-dot/gator/blob/main/handler_reset.go): `handler_reset.go`
- [User config](https://github.com/keepo-dot/gator/blob/main/internal/config/config.go): `internal/config/config.go`
- **Config file**

### Feed management

- [Feed commands](https://github.com/keepo-dot/gator/blob/main/handler_feeds.go): `handler_feeds.go`
- [Add feed](https://github.com/keepo-dot/gator/blob/main/handler_rss.go): `handler_rss.go`
- [Follow feed](https://github.com/keepo-dot/gator/blob/main/handler_follow.go): `handler_follow.go`
- [List follows](https://github.com/keepo-dot/gator/blob/main/handler_following.go): `handler_following.go`
- [Unfollow feed](https://github.com/keepo-dot/gator/blob/main/handler_unfollow.go): `handler_unfollow.go`
- [Feed aggregation](https://github.com/keepo-dot/gator/blob/main/handler_agg.go): `handler_agg.go`
- [RSS fetch and parse](https://github.com/keepo-dot/gator/blob/main/handler_rss.go): `handler_rss.go`

### Persistence

- [Database queries](https://github.com/keepo-dot/gator/tree/main/internal/database): `internal/database`
- **PostgreSQL**

### Other components

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

## Connections

- CLI user → Startup: runs command
- Startup → User config: reads config
- Startup → Database queries: opens database
- Startup → Shared state: builds state
- Startup → Command dispatch: runs dispatch
- Command dispatch → Login middleware: wraps commands
- Command dispatch → User commands: dispatches
- Command dispatch → Registration: dispatches
- Command dispatch → Reset users: dispatches
- Command dispatch → Feed commands: dispatches
- Command dispatch → Add feed: dispatches
- Command dispatch → Follow feed: dispatches
- Command dispatch → List follows: dispatches
- Command dispatch → Unfollow feed: dispatches
- Command dispatch → Feed aggregation: dispatches
- User commands → Database queries: queries users
- User commands → User config: sets current user
- Registration → Database queries: creates user
- Registration → User config: sets current user
- Reset users → Database queries: resets users
- Feed commands → Database queries: lists feeds
- Add feed → Database queries: saves feed and follow
- Follow feed → Database queries: creates follow
- List follows → Database queries: lists follows
- Unfollow feed → Database queries: deletes follow
- Database queries → PostgreSQL: queries
- User config → Config file: reads and writes
- RSS fetch and parse → RSS sources: fetches RSS