# ricardocasares/hoshi architecture

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

- Interactive diagram: https://gitdiagram.com/ricardocasares/hoshi
- Repository: https://github.com/ricardocasares/hoshi

## Overview

1. **Project shape**
   - This is a **single-page frontend application** for browsing a GitHub user’s starred repositories.
   - There is **no backend service in the repo**; the browser app talks directly to the **GitHub REST API**.

2. **Core runtime boundary**
   - The application is primarily written in **Elm** under `src/`.
   - A small **TypeScript entry layer** in `src/main.ts` bootstraps the Elm app and integrates with the Vite build pipeline.
   - `index.html` and `vite.config.ts` indicate the app is delivered as a static frontend bundle.

3. **Primary application state and orchestration**
   - `src/Main.elm` is the center of the architecture: it likely owns the model, update flow, and top-level view for the whole UI.
   - It coordinates user actions such as entering a GitHub username, triggering API fetches, applying filters, sorting, and updating displayed results.

4. **URL / navigation boundary**
   - `src/Routes.elm` suggests the app has explicit route handling, probably to encode state in the URL or support navigation between a home/search view and a browsed user view.
   - This keeps the application shareable and makes the browser URL part of the state boundary.

5. **External API integration**
   - `src/GitHub/API.elm` encapsulates communication with GitHub’s REST endpoints.
   - Based on the README, the app fetches:
     - `GET /users/{username}`
     - `GET /users/{username}/starred`
   - This is the main data ingress into the app, and rate limits for unauthenticated requests are part of the operational constraints.

6. **UI composition layer**
   - `src/UI/` contains reusable presentational components such as `Alert`, `Card`, and `Toast`.
   - These are likely pure Elm view helpers that keep the top-level `Main.elm` from becoming a monolith.
   - The README’s card-based repository browsing and notifications map cleanly to these components.

7. **Interoperability boundary**
   - `src/InteropDefinitions.elm`, `src/InteropPorts.elm`, and `src/Main.elm.d.ts` show a deliberate Elm–JavaScript interop layer.
   - This is the main seam for any browser-only side effects or typed communication between Elm and the TypeScript host.
   - The generated `.d.ts` indicates the TS side is kept in sync with Elm-defined port types.

8. **Styling and presentation system**
   - `src/main.css` plus the README’s Tailwind CSS and DaisyUI references show the UI is styled with a utility/component CSS stack.
   - This affects architecture by separating rendering logic in Elm from design system and responsive behavior in CSS.

9. **Testing and verification**
   - `tests/MainSpec.elm` provides Elm-level tests around the main application logic.
   - `review/` with its own `elm.json` and `ReviewConfig.elm` indicates an additional static-analysis layer using **elm-review**, which is important for maintaining correctness in a strongly typed Elm codebase.

10. **Build, dev, and release pipeline**
   - `package.json`, `bun.lockb`, and `vite.config.ts` show **Bun** is used for scripts and dependency management, while **Vite** handles development server and production bundling.
   - `.github/workflows/ci.yml` and `.github/workflows/deploy.yml` define CI and deployment automation, likely for a static site release.
   - `.husky/pre-commit` suggests local quality gates before changes are committed.

11. **Repo-level boundaries for architecture diagrams**
   - The clearest high-level flow is:
     - browser input / route changes
     - Elm state update in `Main.elm`
     - GitHub API fetch in `GitHub/API.elm`
     - data transformed into searchable/sortable repository state
     - rendered through `UI/*` components
     - optional Elm/TypeScript interop through ports
   - Everything else in the repo supports that flow through tooling, styling, tests, and deployment.

Main entry points: [`src/Main.elm`](https://github.com/ricardocasares/hoshi/blob/main/src/Main.elm) (Main), [`src/main.ts`](https://github.com/ricardocasares/hoshi/blob/main/src/main.ts) (TS bootstrap), [`vite.config.ts`](https://github.com/ricardocasares/hoshi/blob/main/vite.config.ts) (Vite config), [`src/main.css`](https://github.com/ricardocasares/hoshi/blob/main/src/main.css) (Main CSS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App runtime"]
  node_main_elm["Main<br/>elm app<br/>[Main.elm]"]
  node_routes_elm["Routes<br/>elm routing<br/>[Routes.elm]"]
  node_api_elm[("GitHub API<br/>elm client<br/>[API.elm]")]
  node_interop_defs["Interop defs<br/>elm port types"]
  node_interop_ports["Ports<br/>[InteropPorts.elm]"]
end

subgraph group_group_ui["UI layer"]
  node_ui_alert["Alert<br/>view component<br/>[Alert.elm]"]
  node_ui_card["Card<br/>view component<br/>[Card.elm]"]
  node_ui_toast["Toast<br/>view component<br/>[Toast.elm]"]
end

subgraph group_group_platform["Platform"]
  node_index_html["Index HTML<br/>static shell<br/>[index.html]"]
  node_main_ts["TS bootstrap<br/>entry script<br/>[main.ts]"]
  node_main_css["Main CSS<br/>stylesheet<br/>[main.css]"]
  node_vite_config["Vite config<br/>bundler config<br/>[vite.config.ts]"]
  node_package_json["Scripts<br/>tooling manifest<br/>[package.json]"]
  node_elm_json["Elm config<br/>compiler config<br/>[elm.json]"]
end

subgraph group_group_quality["Quality"]
  node_tests_main["Main tests<br/>elm tests<br/>[MainSpec.elm]"]
  node_review_config["Review config<br/>static analysis<br/>[ReviewConfig.elm]"]
  node_ci_workflow["CI<br/>automation<br/>[ci.yml]"]
  node_deploy_workflow["Deploy<br/>automation<br/>[deploy.yml]"]
end

node_browser(("Browser<br/>runtime"))
node_github_api[("GitHub<br/>external api")]

node_browser -->|"loads"| node_index_html
node_index_html -->|"boots"| node_main_ts
node_main_ts -->|"starts"| node_main_elm
node_main_elm -->|"syncs URL"| node_routes_elm
node_main_elm -->|"fetches data"| node_api_elm
node_api_elm -->|"requests"| node_github_api
node_main_elm -->|"renders"| node_ui_alert
node_main_elm -->|"renders"| node_ui_card
node_main_elm -->|"renders"| node_ui_toast
node_main_elm -->|"uses ports"| node_interop_ports
node_interop_ports -->|"typed by"| node_interop_defs
node_main_ts -->|"consumes"| node_interop_defs
node_ui_alert -->|"styled by"| node_main_css
node_ui_card -->|"styled by"| node_main_css
node_ui_toast -->|"styled by"| node_main_css
node_main_ts -->|"bundled by"| node_vite_config
node_vite_config -->|"driven by"| node_package_json
node_main_elm -->|"compiled with"| node_elm_json
node_tests_main -->|"verifies"| node_main_elm
node_review_config -->|"analyzes"| node_main_elm
node_ci_workflow -->|"runs"| node_tests_main
node_ci_workflow -->|"runs"| node_review_config
node_deploy_workflow -->|"builds"| node_vite_config

click node_index_html "https://github.com/ricardocasares/hoshi/blob/main/index.html"
click node_main_ts "https://github.com/ricardocasares/hoshi/blob/main/src/main.ts"
click node_main_elm "https://github.com/ricardocasares/hoshi/blob/main/src/Main.elm"
click node_routes_elm "https://github.com/ricardocasares/hoshi/blob/main/src/Routes.elm"
click node_api_elm "https://github.com/ricardocasares/hoshi/blob/main/src/GitHub/API.elm"
click node_interop_defs "https://github.com/ricardocasares/hoshi/blob/main/src/InteropDefinitions.elm"
click node_interop_ports "https://github.com/ricardocasares/hoshi/blob/main/src/InteropPorts.elm"
click node_ui_alert "https://github.com/ricardocasares/hoshi/blob/main/src/UI/Alert.elm"
click node_ui_card "https://github.com/ricardocasares/hoshi/blob/main/src/UI/Card.elm"
click node_ui_toast "https://github.com/ricardocasares/hoshi/blob/main/src/UI/Toast.elm"
click node_main_css "https://github.com/ricardocasares/hoshi/blob/main/src/main.css"
click node_vite_config "https://github.com/ricardocasares/hoshi/blob/main/vite.config.ts"
click node_package_json "https://github.com/ricardocasares/hoshi/blob/main/package.json"
click node_elm_json "https://github.com/ricardocasares/hoshi/blob/main/elm.json"
click node_tests_main "https://github.com/ricardocasares/hoshi/blob/main/tests/MainSpec.elm"
click node_review_config "https://github.com/ricardocasares/hoshi/blob/main/review/src/ReviewConfig.elm"
click node_ci_workflow "https://github.com/ricardocasares/hoshi/blob/main/.github/workflows/ci.yml"
click node_deploy_workflow "https://github.com/ricardocasares/hoshi/blob/main/.github/workflows/deploy.yml"

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_elm,node_routes_elm,node_api_elm,node_interop_defs,node_interop_ports toneBlue
class node_ui_alert,node_ui_card,node_ui_toast toneAmber
class node_index_html,node_main_ts,node_main_css,node_vite_config,node_package_json,node_elm_json toneMint
class node_tests_main,node_review_config,node_ci_workflow,node_deploy_workflow toneRose
class node_browser,node_github_api toneNeutral
```

## Components

### App runtime

Elm application entrypoints, routing, state, and API integration.

- [Main](https://github.com/ricardocasares/hoshi/blob/main/src/Main.elm): elm app · Top-level Elm model, update, subscriptions, and view composition. · `src/Main.elm`
- [Routes](https://github.com/ricardocasares/hoshi/blob/main/src/Routes.elm): elm routing · URL and navigation state encoding for shareable browser state. · `src/Routes.elm`
- [GitHub API](https://github.com/ricardocasares/hoshi/blob/main/src/GitHub/API.elm): elm client · Elm HTTP boundary for fetching users and starred repositories. · `src/GitHub/API.elm`
- [Interop defs](https://github.com/ricardocasares/hoshi/blob/main/src/InteropDefinitions.elm): elm port types · Shared type definitions for Elm-to-JavaScript communication. · `src/InteropDefinitions.elm`
- [Ports](https://github.com/ricardocasares/hoshi/blob/main/src/InteropPorts.elm): elm ports · Port declarations for browser-side side effects and host integration. · `src/InteropPorts.elm`

### UI layer

Reusable Elm view components and styling concerns.

- [Alert](https://github.com/ricardocasares/hoshi/blob/main/src/UI/Alert.elm): view component · Reusable alert presentation for error and status messaging. · `src/UI/Alert.elm`
- [Card](https://github.com/ricardocasares/hoshi/blob/main/src/UI/Card.elm): view component · Repository card rendering for search results and browsing lists. · `src/UI/Card.elm`
- [Toast](https://github.com/ricardocasares/hoshi/blob/main/src/UI/Toast.elm): view component · Transient notification surface for user feedback. · `src/UI/Toast.elm`

### Platform

Host bootstrap, bundling, and static delivery boundary.

- [Index HTML](https://github.com/ricardocasares/hoshi/blob/main/index.html): static shell · Static HTML entry document for the bundled frontend. · `index.html`
- [TS bootstrap](https://github.com/ricardocasares/hoshi/blob/main/src/main.ts): entry script · TypeScript host that initializes the Elm app and connects build-time tooling. · `src/main.ts`
- [Main CSS](https://github.com/ricardocasares/hoshi/blob/main/src/main.css): stylesheet · Global styling layer for layout, utility classes, and component presentation. · `src/main.css`
- [Vite config](https://github.com/ricardocasares/hoshi/blob/main/vite.config.ts): bundler config · Development server and production bundling configuration. · `vite.config.ts`
- [Scripts](https://github.com/ricardocasares/hoshi/blob/main/package.json): tooling manifest · Bun-managed scripts and dependency entrypoint for the frontend toolchain. · `package.json`
- [Elm config](https://github.com/ricardocasares/hoshi/blob/main/elm.json): compiler config · Elm package and compiler configuration for the application. · `elm.json`

### Quality

Tests, review rules, and automation around correctness and release.

- [Main tests](https://github.com/ricardocasares/hoshi/blob/main/tests/MainSpec.elm): elm tests · Elm test coverage for top-level application behavior. · `tests/MainSpec.elm`
- [Review config](https://github.com/ricardocasares/hoshi/blob/main/review/src/ReviewConfig.elm): static analysis · elm-review rules and configuration for code quality checks. · `review/src/ReviewConfig.elm`
- [CI](https://github.com/ricardocasares/hoshi/blob/main/.github/workflows/ci.yml): automation · Continuous integration workflow for validation and checks. · `.github/workflows/ci.yml`
- [Deploy](https://github.com/ricardocasares/hoshi/blob/main/.github/workflows/deploy.yml): automation · Release workflow for publishing the static frontend bundle. · `.github/workflows/deploy.yml`

### Other components

- **Browser**: runtime · User-facing execution environment and interaction boundary.
- **GitHub**: external api · External REST API used to resolve users and starred repositories.

## Connections

- Browser → Index HTML: loads · The browser starts from the static HTML shell.
- Index HTML → TS bootstrap: boots · The HTML document loads the TypeScript entry script.
- TS bootstrap → Main: starts · The host initializes the Elm application.
- Main → Routes: syncs URL · Application state is coordinated with route state.
- Main → GitHub API: fetches data · Top-level update logic triggers GitHub API requests.
- GitHub API → GitHub: requests · Elm HTTP calls reach the external GitHub REST API.
- Main → Alert: renders · Main view uses alert components for errors and status.
- Main → Card: renders · Main view composes repository cards for search results.
- Main → Toast: renders · Main view emits transient user notifications.
- Main → Ports: uses ports · Elm delegates browser-only side effects through ports.
- Ports → Interop defs: typed by · Port signatures are kept aligned with shared definitions.
- TS bootstrap → Interop defs: consumes · The TypeScript host keeps its interop view in sync.
- Alert → Main CSS: styled by · Component rendering is shaped by the global stylesheet.
- Card → Main CSS: styled by · Card presentation depends on the shared CSS layer.
- Toast → Main CSS: styled by · Toast presentation depends on the shared CSS layer.
- TS bootstrap → Vite config: bundled by · The entry script is served and built through Vite.
- Vite config → Scripts: driven by · Bundler behavior is orchestrated through project scripts and deps.
- Main → Elm config: compiled with · Elm application code is governed by Elm compiler config.
- Main tests → Main: verifies · Tests exercise the top-level application behavior.
- Review config → Main: analyzes · elm-review enforces project-specific correctness rules.
- CI → Main tests: runs · CI validates the repository with tests and checks.
- CI → Review config: runs · CI includes static analysis gates.
- Deploy → Vite config: builds · Release automation produces the bundled frontend artifact.
