# themakarov/ashbugquerytoomanyusers architecture

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

- Interactive diagram: https://gitdiagram.com/themakarov/ashbugquerytoomanyusers
- Repository: https://github.com/themakarov/ashbugquerytoomanyusers

## Overview

1. **High-level shape**
   - This is a **Phoenix web application** named `Illustration`.
   - The architecture is split into a **web layer** (`lib/illustration_web`), a **domain/data layer** (`lib/illustration`, `lib/illustration/accounts`), and a **database/persistence layer** (`lib/illustration/repo.ex`, `priv/repo/migrations`).

2. **Request entry path**
   - Incoming HTTP traffic enters through the Phoenix **Endpoint** (`lib/illustration_web/endpoint.ex`), then flows through the **Router** (`lib/illustration_web/router.ex`).
   - The router dispatches to controllers, currently centered on the **page controller** and error handlers.

3. **Web presentation layer**
   - The main visible UI appears to be a **home/landing page** rendered by `PageController` and `page_html/home.html.heex`.
   - Shared presentation pieces live in `lib/illustration_web/components`, including:
     - `core_components.ex` for reusable UI primitives
     - `layouts.ex` plus `app.html.heex` and `root.html.heex` for page structure and wrapping
   - This indicates a standard Phoenix server-rendered HTML application rather than a separate SPA frontend.

4. **Error handling boundary**
   - The repo explicitly defines both **HTML and JSON error surfaces** via `error_html.ex` and `error_json.ex`.
   - That suggests the app can serve browser pages and API-style responses, even though the visible feature set in the tree is mostly HTML-oriented.

5. **Domain/account subsystem**
   - The `Accounts` area is the primary business/domain module visible in the repo:
     - `lib/illustration/Accounts.ex`
     - `lib/illustration/accounts/user.ex`
     - `lib/illustration/accounts/token.ex`
     - `lib/illustration/accounts/secret.ex`
   - This subsystem likely models authentication or identity-related data, with `user`, `token`, and `secret` as the main entities.

6. **Persistence layer**
   - Database access is handled through `lib/illustration/repo.ex`, which is the app’s repository boundary.
   - `priv/repo/migrations` contains the schema evolution scripts, including migrations for extensions and initial tables/resources.
   - `priv/resource_snapshots/repo/...` contains JSON snapshots for `extensions`, `users`, and `tokens`, which suggests the data model is tracked as generated resource metadata in addition to SQL migrations.

7. **Application/runtime composition**
   - `lib/illustration/application.ex` is the top-level OTP application entrypoint and is responsible for starting the supervision tree.
   - Based on the file layout, the main runtime services are the **Repo**, **Endpoint**, and likely support components such as the **Mailer**.

8. **Mail subsystem**
   - `lib/illustration/mailer.ex` exists as a dedicated email boundary.
   - Even if not yet heavily used in the visible routes, this separates outbound email from controllers and domain logic, which is important for account flows like confirmation, reset, or notifications.

9. **Configuration and environment split**
   - Runtime behavior is configured through the standard Phoenix config files:
     - `config/config.exs`
     - `config/dev.exs`
     - `config/prod.exs`
     - `config/runtime.exs`
     - `config/test.exs`
   - This means the app is environment-driven, with different database, endpoint, and production runtime settings per environment.

10. **Assets and frontend build**
   - Frontend assets are isolated under `assets/`:
     - `assets/css/app.css`
     - `assets/js/app.js`
     - `assets/tailwind.config.js`
   - This indicates a conventional Phoenix asset pipeline with CSS/JS bundling and Tailwind-based styling, but the frontend remains server-rendered.

11. **Internationalization and telemetry**
   - `lib/illustration_web/gettext.ex` and `priv/gettext/...` provide localization support.
   - `lib/illustration_web/telemetry.ex` suggests Phoenix/BEAM telemetry instrumentation is wired in for request and runtime metrics.

12. **Testing structure**
   - Tests are organized to mirror the main layers:
     - controller tests under `test/illustration_web/controllers`
     - shared test support in `test/support`
   - This points to separation between web behavior tests and lower-level data/support helpers.

13. **Operational boundary**
   - `priv/static` contains deployable public assets like images and `robots.txt`.
   - `README.md` describes the standard Phoenix development and production startup path, confirming the app is meant to be run as a conventional Phoenix service with a database-backed backend.

14. **Architecture summary for a diagram**
   - A useful diagram would show:
     - **Browser/client** → **Endpoint/Router** → **Controllers/Views/Components** → **Domain modules** → **Repo/DB**
     - parallel supporting services for **Mailer**, **gettext**, **telemetry**, and **static assets**
   - The main business boundary visible in the repo is the **Accounts** subsystem, while the current UI surface is a **simple server-rendered homepage plus error pages**.

Main entry points: [`lib/illustration_web/endpoint.ex`](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/endpoint.ex) (Endpoint), [`lib/illustration/Accounts.ex`](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration/Accounts.ex) (Accounts), [`lib/illustration_web/router.ex`](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/router.ex) (Router), [`lib/illustration/application.ex`](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration/application.ex) (Application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web layer"]
  node_endpoint["Endpoint<br/>[endpoint.ex]"]
  node_router["Router<br/>route dispatch<br/>[router.ex]"]
  node_page_controller["Page controller<br/>html controller<br/>[page_controller.ex]"]
  node_page_view["Page HTML<br/>html view<br/>[page_html.ex]"]
  node_home_template["Home page<br/>heex template<br/>[home.html.heex]"]
  node_layouts["Layouts<br/>layout components<br/>[layouts.ex]"]
  node_core_components["Core components<br/>ui primitives<br/>[core_components.ex]"]
  node_error_html["HTML errors<br/>error view<br/>[error_html.ex]"]
  node_error_json["JSON errors<br/>error view<br/>[error_json.ex]"]
end

subgraph group_domain["Domain layer"]
  node_accounts["Accounts<br/>domain context<br/>[Accounts.ex]"]
  node_user["User<br/>account entity<br/>[user.ex]"]
  node_token["Token<br/>account entity<br/>[token.ex]"]
  node_secret["Secret<br/>account entity<br/>[secret.ex]"]
end

subgraph group_persistence["Persistence"]
  node_repo[("Repo<br/>database boundary<br/>[repo.ex]")]
  node_migrations["Migrations"]
  node_snapshots["Snapshots<br/>resource metadata"]
end

subgraph group_runtime["Runtime support"]
  node_application["Application<br/>otp supervision<br/>[application.ex]"]
  node_mailer["Mailer<br/>email boundary<br/>[mailer.ex]"]
  node_gettext["Gettext<br/>localization<br/>[gettext.ex]"]
  node_telemetry["Telemetry<br/>metrics hooks<br/>[telemetry.ex]"]
end

subgraph group_assets["Assets"]
  node_assets_js["JS bundle<br/>frontend asset<br/>[app.js]"]
  node_assets_css["CSS bundle<br/>frontend asset<br/>[app.css]"]
  node_static["Static files<br/>public assets"]
end

node_client(("Client<br/>browser/http"))

node_client -->|"HTTP"| node_endpoint
node_endpoint -->|"dispatches"| node_router
node_router -->|"routes"| node_page_controller
node_router -.->|"errors"| node_error_html
node_router -.->|"errors"| node_error_json
node_page_controller -->|"renders"| node_page_view
node_page_view -->|"uses"| node_home_template
node_page_view -->|"wraps"| node_layouts
node_page_view -.->|"composes"| node_core_components
node_accounts -->|"manages"| node_user
node_accounts -->|"manages"| node_token
node_accounts -->|"manages"| node_secret
node_accounts -->|"persists via"| node_repo
node_repo -->|"schema"| node_migrations
node_repo -.->|"tracks"| node_snapshots
node_application -->|"starts"| node_endpoint
node_application -->|"starts"| node_repo
node_application -->|"starts"| node_mailer
node_application -.->|"instruments"| node_telemetry
node_page_controller -.->|"uses"| node_accounts
node_accounts -.->|"notifies"| node_mailer
node_router -.->|"localizes"| node_gettext
node_endpoint -.->|"observes"| node_telemetry
node_assets_js -.->|"served by"| node_endpoint
node_assets_css -.->|"served by"| node_endpoint
node_static -.->|"served by"| node_endpoint

click node_endpoint "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/endpoint.ex"
click node_router "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/router.ex"
click node_page_controller "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/controllers/page_controller.ex"
click node_page_view "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/controllers/page_html.ex"
click node_home_template "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/controllers/page_html/home.html.heex"
click node_layouts "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/components/layouts.ex"
click node_core_components "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/components/core_components.ex"
click node_error_html "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/controllers/error_html.ex"
click node_error_json "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/controllers/error_json.ex"
click node_accounts "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration/Accounts.ex"
click node_user "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration/accounts/user.ex"
click node_token "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration/accounts/token.ex"
click node_secret "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration/accounts/secret.ex"
click node_repo "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration/repo.ex"
click node_migrations "https://github.com/themakarov/ashbugquerytoomanyusers/tree/main/priv/repo/migrations"
click node_snapshots "https://github.com/themakarov/ashbugquerytoomanyusers/tree/main/priv/resource_snapshots/repo"
click node_application "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration/application.ex"
click node_mailer "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration/mailer.ex"
click node_gettext "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/gettext.ex"
click node_telemetry "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/telemetry.ex"
click node_assets_js "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/assets/js/app.js"
click node_assets_css "https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/assets/css/app.css"
click node_static "https://github.com/themakarov/ashbugquerytoomanyusers/tree/main/priv/static"

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_endpoint,node_router,node_page_controller,node_page_view,node_home_template,node_layouts,node_core_components,node_error_html,node_error_json toneBlue
class node_accounts,node_user,node_token,node_secret toneAmber
class node_repo,node_migrations,node_snapshots toneMint
class node_application,node_mailer,node_gettext,node_telemetry toneRose
class node_assets_js,node_assets_css,node_static toneIndigo
class node_client toneNeutral
```

## Components

### Web layer

HTTP entry, routing, controllers, HTML rendering, and shared presentation components.

- [Endpoint](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/endpoint.ex): phoenix endpoint · Top-level HTTP boundary for requests and responses. · `lib/illustration_web/endpoint.ex`
- [Router](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/router.ex): route dispatch · Maps incoming requests to controllers and error surfaces. · `lib/illustration_web/router.ex`
- [Page controller](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/controllers/page_controller.ex): html controller · Main page controller for the landing/home route. · `lib/illustration_web/controllers/page_controller.ex`
- [Page HTML](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/controllers/page_html.ex): html view · HTML rendering module for page templates. · `lib/illustration_web/controllers/page_html.ex`
- [Home page](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/controllers/page_html/home.html.heex): heex template · Landing page template rendered by the page controller. · `lib/illustration_web/controllers/page_html/home.html.heex`
- [Layouts](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/components/layouts.ex): layout components · Shared application and root page wrappers. · `lib/illustration_web/components/layouts.ex`
- [Core components](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/components/core_components.ex): ui primitives · Reusable Phoenix UI components used across pages. · `lib/illustration_web/components/core_components.ex`
- [HTML errors](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/controllers/error_html.ex): error view · HTML error response surface for browser requests. · `lib/illustration_web/controllers/error_html.ex`
- [JSON errors](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/controllers/error_json.ex): error view · JSON error response surface for API-style requests. · `lib/illustration_web/controllers/error_json.ex`

### Domain layer

Accounts and application business logic.

- [Accounts](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration/Accounts.ex): domain context · Primary business context for users, tokens, and secrets. · `lib/illustration/Accounts.ex`
- [User](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration/accounts/user.ex): account entity · Core user record in the accounts domain. · `lib/illustration/accounts/user.ex`
- [Token](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration/accounts/token.ex): account entity · Token model for authentication or verification flows. · `lib/illustration/accounts/token.ex`
- [Secret](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration/accounts/secret.ex): account entity · Secret-related account data or credential model. · `lib/illustration/accounts/secret.ex`

### Persistence

Repo boundary and database schema evolution.

- [Repo](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration/repo.ex): database boundary · Ecto repository used by the application for persistence. · `lib/illustration/repo.ex`
- [Migrations](https://github.com/themakarov/ashbugquerytoomanyusers/tree/main/priv/repo/migrations): schema migrations · Database migration scripts defining schema changes. · `priv/repo/migrations`
- [Snapshots](https://github.com/themakarov/ashbugquerytoomanyusers/tree/main/priv/resource_snapshots/repo): resource metadata · Generated resource snapshots for users, tokens, and extensions. · `priv/resource_snapshots/repo`

### Runtime support

OTP application, mail, gettext, telemetry, and config.

- [Application](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration/application.ex): otp supervision · OTP application entrypoint and supervision tree. · `lib/illustration/application.ex`
- [Mailer](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration/mailer.ex): email boundary · Outbound email adapter boundary for account-related flows. · `lib/illustration/mailer.ex`
- [Gettext](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/gettext.ex): localization · Translation and localization support for the web layer. · `lib/illustration_web/gettext.ex`
- [Telemetry](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/lib/illustration_web/telemetry.ex): metrics hooks · Instrumentation boundary for request and runtime telemetry. · `lib/illustration_web/telemetry.ex`

### Assets

Frontend build inputs and static public files.

- [JS bundle](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/assets/js/app.js): frontend asset · Client-side JavaScript entrypoint. · `assets/js/app.js`
- [CSS bundle](https://github.com/themakarov/ashbugquerytoomanyusers/blob/main/assets/css/app.css): frontend asset · Main stylesheet for the server-rendered UI. · `assets/css/app.css`
- [Static files](https://github.com/themakarov/ashbugquerytoomanyusers/tree/main/priv/static): public assets · Deployable public assets such as images and robots.txt. · `priv/static`

### Other components

- **Client**: browser/http · External browser or HTTP client consuming the Phoenix app.

## Connections

- Client → Endpoint: HTTP · Browser or client sends requests to the Phoenix endpoint.
- Endpoint → Router: dispatches · Endpoint forwards requests into the router.
- Router → Page controller: routes · Router dispatches the landing page to the page controller.
- Router → HTML errors: errors · Router exposes HTML error handling for browser requests.
- Router → JSON errors: errors · Router exposes JSON error handling for API-style requests.
- Page controller → Page HTML: renders · Controller renders the HTML view module.
- Page HTML → Home page: uses · HTML view selects the home template.
- Page HTML → Layouts: wraps · View uses shared layout components.
- Page HTML → Core components: composes · View composes reusable UI primitives.
- Accounts → User: manages · Accounts context manages user records.
- Accounts → Token: manages · Accounts context manages tokens.
- Accounts → Secret: manages · Accounts context manages secret-related data.
- Accounts → Repo: persists via · Domain data is stored through the repository boundary.
- Repo → Migrations: schema · Repository is backed by migration-defined schema.
- Repo → Snapshots: tracks · Repository resources are tracked with generated snapshots.
- Application → Endpoint: starts · OTP supervision starts the web endpoint.
- Application → Repo: starts · OTP supervision starts the database repo.
- Application → Mailer: starts · OTP supervision starts the mail boundary.
- Application → Telemetry: instruments · Application wiring includes telemetry support.
- Page controller → Accounts: uses · Web layer can call into the accounts context.
- Accounts → Mailer: notifies · Account workflows may send outbound email.
- Router → Gettext: localizes · Web responses can use translation support.
- Endpoint → Telemetry: observes · Endpoint request handling is instrumented.
- JS bundle → Endpoint: served by · JavaScript bundle is delivered through the web app.
- CSS bundle → Endpoint: served by · CSS bundle is delivered through the web app.
- Static files → Endpoint: served by · Public static files are exposed through the Phoenix app.
