How ricardocasares/hoshi works
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: Main.elm Main · main.ts TS bootstrap · vite.config.ts Vite config · main.css Main CSS
Components 20
App runtime
Elm application entrypoints, routing, state, and API integration.
- Main · Top-level Elm model, update, subscriptions, and view composition.
src/Main.elm - Routes · URL and navigation state encoding for shareable browser state.
src/Routes.elm - GitHub API · Elm HTTP boundary for fetching users and starred repositories.
src/GitHub/API.elm - Interop defs · Shared type definitions for Elm-to-JavaScript communication.
src/InteropDefinitions.elm - Ports · Port declarations for browser-side side effects and host integration.
src/InteropPorts.elm
UI layer
Reusable Elm view components and styling concerns.
Platform
Host bootstrap, bundling, and static delivery boundary.
- Index HTML · Static HTML entry document for the bundled frontend.
index.html - TS bootstrap · TypeScript host that initializes the Elm app and connects build-time tooling.
src/main.ts - Main CSS · Global styling layer for layout, utility classes, and component presentation.
src/main.css - Vite config · Development server and production bundling configuration.
vite.config.ts - Scripts · Bun-managed scripts and dependency entrypoint for the frontend toolchain.
package.json - Elm config · Elm package and compiler configuration for the application.
elm.json
Quality
Tests, review rules, and automation around correctness and release.
- Main tests · Elm test coverage for top-level application behavior.
tests/MainSpec.elm - Review config · elm-review rules and configuration for code quality checks.
review/src/ReviewConfig.elm - CI · Continuous integration workflow for validation and checks.
.github/workflows/ci.yml - Deploy · Release workflow for publishing the static frontend bundle.
.github/workflows/deploy.yml
Other components
- Browser · User-facing execution environment and interaction boundary.
- GitHub · External REST API used to resolve users and starred repositories.
Connections 23
- 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.