# mikestefanello/pagoda architecture

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

- Interactive diagram: https://gitdiagram.com/mikestefanello/pagoda
- Repository: https://github.com/mikestefanello/pagoda

## Overview

Pagoda is a Go full-stack web starter kit. Its main workflow is an HTTP request through routing and middleware to a feature handler, which processes forms and domain services, accesses persistent state when needed, and renders server-side HTML. Authentication and administration are distinct domain paths; cache, background tasks, and file delivery are additional capabilities documented by the README. The sampled sources establish router setup, authentication persistence, and Ent access; some feature wiring is inferred only from documented capabilities and the repository tree.

Main entry points: [`pkg/handlers/router.go`](https://github.com/mikestefanello/pagoda/blob/main/pkg/handlers/router.go) (Router and Middleware), [`pkg/services/auth.go`](https://github.com/mikestefanello/pagoda/blob/main/pkg/services/auth.go) (Authentication), [`ent/client.go`](https://github.com/mikestefanello/pagoda/blob/main/ent/client.go) (Ent ORM), [`pkg/handlers/handlers.go`](https://github.com/mikestefanello/pagoda/blob/main/pkg/handlers/handlers.go) (Feature Handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Runtime"]
  node_webapp["Web App<br/>[main.go]"]
  node_router["Router and Middleware<br/>[router.go]"]
  node_handlers["Feature Handlers<br/>[handlers.go]"]
end

subgraph group_domain["Domain Services"]
  node_auth_handlers["Auth Routes<br/>[auth.go]"]
  node_admin_handlers["Admin Routes<br/>[admin.go]"]
  node_files_handlers["File Routes<br/>[files.go]"]
  node_search_handlers["Search Routes<br/>[search.go]"]
  node_task_handlers["Task Routes<br/>[task.go]"]
  node_auth_service["Authentication<br/>[auth.go]"]
  node_services["Service Container<br/>[container.go]"]
  node_mail["Email Service<br/>[mail.go]"]
end

subgraph group_data["Data and Jobs"]
  node_orm["Ent ORM<br/>[client.go]"]
  node_schema["User Schema<br/>[user.go]"]
  node_database[("SQLite Store<br/>[client.go]")]
  node_cache["Cache Service<br/>[cache.go]"]
  node_tasks["Task Queues<br/>[register.go]"]
end

subgraph group_ui["Server UI"]
  node_ui["UI Renderer<br/>[ui.go]"]
  node_pages["Page Views"]
  node_forms["Form Processing<br/>[submission.go]"]
  node_static["Static Assets<br/>[fs.go]"]
  node_email_templates["Email Views<br/>[auth.go]"]
end

node_visitor(("Browser"))

node_visitor -->|"sends request"| node_router
node_webapp -->|"builds routes"| node_router
node_webapp -->|"starts runner"| node_tasks
node_router -->|"registers routes"| node_handlers
node_router -->|"serves assets"| node_static
node_router -->|"loads user"| node_auth_service
node_auth_handlers -->|"handles auth"| node_auth_service
node_admin_handlers -->|"manages entities"| node_orm
node_auth_service -->|"reads and writes"| node_orm
node_orm -->|"queries"| node_database
node_orm -->|"models"| node_schema
node_handlers -->|"processes submissions"| node_forms
node_handlers -->|"renders pages"| node_pages
node_pages -->|"uses components"| node_ui
node_files_handlers -->|"serves files"| node_static
node_search_handlers -->|"renders results"| node_pages
node_task_handlers -->|"monitors queues"| node_tasks
node_services -->|"provides cache"| node_cache
node_auth_service -.->|"sends messages"| node_mail
node_email_templates -.->|"supplies content"| node_mail

click node_webapp "https://github.com/mikestefanello/pagoda/blob/main/cmd/web/main.go"
click node_router "https://github.com/mikestefanello/pagoda/blob/main/pkg/handlers/router.go"
click node_handlers "https://github.com/mikestefanello/pagoda/blob/main/pkg/handlers/handlers.go"
click node_auth_handlers "https://github.com/mikestefanello/pagoda/blob/main/pkg/handlers/auth.go"
click node_admin_handlers "https://github.com/mikestefanello/pagoda/blob/main/pkg/handlers/admin.go"
click node_files_handlers "https://github.com/mikestefanello/pagoda/blob/main/pkg/handlers/files.go"
click node_search_handlers "https://github.com/mikestefanello/pagoda/blob/main/pkg/handlers/search.go"
click node_task_handlers "https://github.com/mikestefanello/pagoda/blob/main/pkg/handlers/task.go"
click node_auth_service "https://github.com/mikestefanello/pagoda/blob/main/pkg/services/auth.go"
click node_services "https://github.com/mikestefanello/pagoda/blob/main/pkg/services/container.go"
click node_mail "https://github.com/mikestefanello/pagoda/blob/main/pkg/services/mail.go"
click node_orm "https://github.com/mikestefanello/pagoda/blob/main/ent/client.go"
click node_schema "https://github.com/mikestefanello/pagoda/blob/main/ent/schema/user.go"
click node_database "https://github.com/mikestefanello/pagoda/blob/main/ent/client.go"
click node_cache "https://github.com/mikestefanello/pagoda/blob/main/pkg/services/cache.go"
click node_tasks "https://github.com/mikestefanello/pagoda/blob/main/pkg/tasks/register.go"
click node_ui "https://github.com/mikestefanello/pagoda/blob/main/pkg/ui/ui.go"
click node_pages "https://github.com/mikestefanello/pagoda/tree/main/pkg/ui/pages"
click node_forms "https://github.com/mikestefanello/pagoda/blob/main/pkg/form/submission.go"
click node_static "https://github.com/mikestefanello/pagoda/blob/main/public/fs.go"
click node_email_templates "https://github.com/mikestefanello/pagoda/blob/main/pkg/ui/emails/auth.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_webapp,node_router,node_handlers,node_visitor toneBlue
class node_auth_handlers,node_admin_handlers,node_files_handlers,node_search_handlers,node_task_handlers,node_auth_service,node_services,node_mail toneAmber
class node_orm,node_schema,node_database,node_cache,node_tasks toneMint
class node_ui,node_pages,node_forms,node_static,node_email_templates toneRose
```

## Components

### Web Runtime

- [Web App](https://github.com/mikestefanello/pagoda/blob/main/cmd/web/main.go): `cmd/web/main.go`
- [Router and Middleware](https://github.com/mikestefanello/pagoda/blob/main/pkg/handlers/router.go): `pkg/handlers/router.go`
- [Feature Handlers](https://github.com/mikestefanello/pagoda/blob/main/pkg/handlers/handlers.go): `pkg/handlers/handlers.go`

### Domain Services

- [Auth Routes](https://github.com/mikestefanello/pagoda/blob/main/pkg/handlers/auth.go): `pkg/handlers/auth.go`
- [Admin Routes](https://github.com/mikestefanello/pagoda/blob/main/pkg/handlers/admin.go): `pkg/handlers/admin.go`
- [File Routes](https://github.com/mikestefanello/pagoda/blob/main/pkg/handlers/files.go): `pkg/handlers/files.go`
- [Search Routes](https://github.com/mikestefanello/pagoda/blob/main/pkg/handlers/search.go): `pkg/handlers/search.go`
- [Task Routes](https://github.com/mikestefanello/pagoda/blob/main/pkg/handlers/task.go): `pkg/handlers/task.go`
- [Authentication](https://github.com/mikestefanello/pagoda/blob/main/pkg/services/auth.go): `pkg/services/auth.go`
- [Service Container](https://github.com/mikestefanello/pagoda/blob/main/pkg/services/container.go): `pkg/services/container.go`
- [Email Service](https://github.com/mikestefanello/pagoda/blob/main/pkg/services/mail.go): `pkg/services/mail.go`

### Data and Jobs

- [Ent ORM](https://github.com/mikestefanello/pagoda/blob/main/ent/client.go): `ent/client.go`
- [User Schema](https://github.com/mikestefanello/pagoda/blob/main/ent/schema/user.go): `ent/schema/user.go`
- [SQLite Store](https://github.com/mikestefanello/pagoda/blob/main/ent/client.go): `ent/client.go`
- [Cache Service](https://github.com/mikestefanello/pagoda/blob/main/pkg/services/cache.go): `pkg/services/cache.go`
- [Task Queues](https://github.com/mikestefanello/pagoda/blob/main/pkg/tasks/register.go): `pkg/tasks/register.go`

### Server UI

- [UI Renderer](https://github.com/mikestefanello/pagoda/blob/main/pkg/ui/ui.go): `pkg/ui/ui.go`
- [Page Views](https://github.com/mikestefanello/pagoda/tree/main/pkg/ui/pages): `pkg/ui/pages`
- [Form Processing](https://github.com/mikestefanello/pagoda/blob/main/pkg/form/submission.go): `pkg/form/submission.go`
- [Static Assets](https://github.com/mikestefanello/pagoda/blob/main/public/fs.go): `public/fs.go`
- [Email Views](https://github.com/mikestefanello/pagoda/blob/main/pkg/ui/emails/auth.go): `pkg/ui/emails/auth.go`

### Other components

- **Browser**

## Connections

- Browser → Router and Middleware: sends request
- Web App → Router and Middleware: builds routes
- Web App → Task Queues: starts runner
- Router and Middleware → Feature Handlers: registers routes
- Router and Middleware → Static Assets: serves assets
- Router and Middleware → Authentication: loads user
- Auth Routes → Authentication: handles auth
- Admin Routes → Ent ORM: manages entities
- Authentication → Ent ORM: reads and writes
- Ent ORM → SQLite Store: queries
- Ent ORM → User Schema: models
- Feature Handlers → Form Processing: processes submissions
- Feature Handlers → Page Views: renders pages
- Page Views → UI Renderer: uses components
- File Routes → Static Assets: serves files
- Search Routes → Page Views: renders results
- Task Routes → Task Queues: monitors queues
- Service Container → Cache Service: provides cache
- Authentication → Email Service: sends messages
- Email Views → Email Service: supplies content