# mizcausevic-dev/portfolio-constellation architecture

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

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/portfolio-constellation
- Repository: https://github.com/mizcausevic-dev/portfolio-constellation

## Overview

Purpose and principal workflow: A portfolio dashboard for visitors exploring one engineer’s public GitHub repositories, grouped into named platforms and industry verticals. The visitor initiates the main workflow by opening the site: it renders a build-time repository snapshot, derives cleaned and classified data for its visualizations and filterable grid, then attempts a live GitHub API refresh after first paint. Separately, a scheduled GitHub Action refreshes the snapshot used by future builds.

Components

**Application and rendering**
- **Browser entry and hydration** — `src/main.tsx`: mounts the React app in the browser, hydrating prerendered HTML when present or rendering a new tree otherwise.
- **Dashboard orchestration** — `src/App.tsx`: owns snapshot, live-refresh and filter state; cleans repository data, computes statistics, and composes the page’s major views.
- **Server prerender** — `src/entry-server.tsx`: renders the app to HTML for prerendering; its documented render path uses the baked snapshot because effects do not run.

**Repository data and interpretation**
- **Bundled snapshot** — `src/data/repos.json`: checked-in repository snapshot bundled into the build and used for the initial render.
- **Snapshot ingestion and live refresh** — `src/lib/data.ts`: exposes the baked snapshot, fetches public repositories from the GitHub API, and caches successful results in browser local storage.
- **Repository curation** — `src/lib/curate.ts`: supplies the cleaned repository set used by the dashboard; the app describes this as excluding forks, archived repositories, and stubs.
- **Cluster and vertical classifier** — `src/lib/classifier.ts`: assigns platform clusters and industry verticals using explicit name allowlists and topic/name heuristics, and classifies freshness.
- **Portfolio aggregation** — `src/lib/aggregate.ts`: computes overview counts and language, cluster, vertical, and signal statistics from repositories.

**Portfolio exploration UI**
- **Portfolio overview and visual atlas** — `src/components/Hero.tsx`: presents headline counts and snapshot/live status. The broader page also includes featured, cluster, language, and industry views.
- **Constellation explorer** — `src/components/PortfolioConstellation.tsx`: renders the interactive platform constellation, repository leaves, details, and platform selection controls.
- **Repository search and filters** — `src/components/Filters.tsx`: provides composable search, platform, vertical, language, and freshness filters for the repository grid.

**Snapshot refresh**
- **Scheduled snapshot refresh** — `.github/workflows/refresh-snapshot.yml`: the README documents this GitHub Action as running every six hours and committing changed snapshot data; workflow steps are not included in the sampled source.

**External actors and interfaces**
- **Portfolio visitor** — `null` repository path: opens the site and interacts with its visualizations and filters.
- **GitHub REST API** — `null` repository path: supplies public repository data to the client-side live refresh and, according to the README, the snapshot-refresh process.
- **Scheduled GitHub Actions runner** — `null` repository path: executes the documented periodic snapshot-refresh workflow.

Relationships
- Portfolio visitor -> Browser entry and hydration: opens the site; the entry selects hydration or client rendering based on whether prerendered HTML exists.
- Browser entry and hydration -> Dashboard orchestration: mounts or hydrates the React app.
- Server prerender -> Dashboard orchestration: renders the app to HTML using the baked snapshot.
- Dashboard orchestration -> Bundled snapshot: initializes its snapshot state from the build-time data.
- Dashboard orchestration -> Snapshot ingestion and live refresh: requests a live refresh after first paint and accepts a non-null result only when it is not smaller than the current repository set.
- Snapshot ingestion and live refresh -> GitHub REST API: fetches public repositories by user, handling pagination and mapping API fields into repository records.
- Snapshot ingestion and live refresh -> Snapshot ingestion and live refresh: reads and writes a six-hour browser local-storage cache for live results.
- Dashboard orchestration -> Repository curation: obtains the cleaned set that drives counts and rendered repository views.
- Repository curation -> Cluster and vertical classifier: uses repository classification and freshness in deriving the curated dashboard data.
- Dashboard orchestration -> Portfolio aggregation: computes portfolio statistics from the cleaned set.
- Dashboard orchestration -> Portfolio overview and visual atlas: supplies overview values and derived statistics to the page’s visual sections.
- Dashboard orchestration -> Constellation explorer: supplies cluster statistics; selection updates the dashboard’s platform filter.
- Dashboard orchestration -> Repository search and filters: supplies the grid’s filter state and update handler.
- Scheduled GitHub Actions runner -> Scheduled snapshot refresh: starts the documented periodic workflow.
- Scheduled snapshot refresh -> GitHub REST API: the README documents repository-list refresh via `gh api`.
- Scheduled snapshot refresh -> Bundled snapshot: commits changed repository-list data for subsequent builds.

Coverage limits: The sampled source does not include the refresh script, workflow contents, repository JSON, `RepoGrid`, or most visualization components. The README establishes the scheduled refresh behavior, but its exact command sequence and deployment wiring could not be verified here.

Main entry points: [`src/App.tsx`](https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/App.tsx) (Dashboard Orchestration), [`src/lib/data.ts`](https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/lib/data.ts) (Snapshot and Live Refresh), [`.github/workflows/refresh-snapshot.yml`](https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/.github/workflows/refresh-snapshot.yml) (Scheduled Snapshot Refresh), [`src/main.tsx`](https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/main.tsx) (Browser Entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["Application and Rendering"]
  node_browser_entry["Browser Entry<br/>entry point"]
  node_dashboard["Dashboard Orchestration<br/>[App.tsx]"]
  node_server_prerender["Server Prerender<br/>renderer"]
end

subgraph group_repository_data["Repository Data and Interpretation"]
  node_snapshot["Bundled Snapshot<br/>repository data"]
  node_data_refresh["Snapshot and Live Refresh<br/>data service"]
  node_curation["Repository Curation<br/>data processing"]
  node_classifier["Cluster and Vertical Classifier<br/>[classifier.ts]"]
  node_aggregation["Portfolio Aggregation<br/>[aggregate.ts]"]
end

subgraph group_exploration_ui["Portfolio Exploration UI"]
  node_overview["Portfolio Overview<br/>[Hero.tsx]"]
  node_constellation["Constellation Explorer<br/>interactive view"]
  node_filters["Repository Search and Filters<br/>filter controls"]
end

subgraph group_snapshot_refresh["Snapshot Refresh"]
  node_scheduled_refresh["Scheduled Snapshot Refresh<br/>workflow"]
end

node_visitor(("Portfolio Visitor<br/>external actor"))
node_github_api["GitHub REST API<br/>external API"]
node_actions_runner(("Scheduled Actions Runner<br/>external actor"))

node_visitor -->|"opens site"| node_browser_entry
node_browser_entry -->|"mounts or hydrates"| node_dashboard
node_server_prerender -->|"renders HTML"| node_dashboard
node_dashboard -->|"initializes from"| node_snapshot
node_dashboard -->|"requests refresh"| node_data_refresh
node_data_refresh -->|"fetches repositories"| node_github_api
node_data_refresh -->|"caches results"| node_data_refresh
node_dashboard -->|"gets cleaned set"| node_curation
node_curation -->|"uses classification"| node_classifier
node_dashboard -->|"computes statistics"| node_aggregation
node_dashboard -->|"supplies values"| node_overview
node_dashboard -->|"supplies cluster stats"| node_constellation
node_constellation -->|"updates platform filter"| node_dashboard
node_dashboard -->|"supplies filter state"| node_filters
node_actions_runner -->|"starts workflow"| node_scheduled_refresh
node_scheduled_refresh -->|"refreshes repository list"| node_github_api
node_scheduled_refresh -->|"commits changes"| node_snapshot

click node_browser_entry "https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/main.tsx"
click node_dashboard "https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/App.tsx"
click node_server_prerender "https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/entry-server.tsx"
click node_snapshot "https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/data/repos.json"
click node_data_refresh "https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/lib/data.ts"
click node_curation "https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/lib/curate.ts"
click node_classifier "https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/lib/classifier.ts"
click node_aggregation "https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/lib/aggregate.ts"
click node_overview "https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/components/Hero.tsx"
click node_constellation "https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/components/PortfolioConstellation.tsx"
click node_filters "https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/components/Filters.tsx"
click node_scheduled_refresh "https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/.github/workflows/refresh-snapshot.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_browser_entry,node_dashboard,node_server_prerender toneBlue
class node_snapshot,node_data_refresh,node_curation,node_classifier,node_aggregation toneAmber
class node_overview,node_constellation,node_filters,node_github_api toneMint
class node_scheduled_refresh toneRose
class node_visitor,node_actions_runner toneIndigo
```

## Components

### Application and Rendering

- [Browser Entry](https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/main.tsx): entry point · `src/main.tsx`
- [Dashboard Orchestration](https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/App.tsx): application · `src/App.tsx`
- [Server Prerender](https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/entry-server.tsx): renderer · `src/entry-server.tsx`

### Repository Data and Interpretation

- [Bundled Snapshot](https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/data/repos.json): repository data · `src/data/repos.json`
- [Snapshot and Live Refresh](https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/lib/data.ts): data service · `src/lib/data.ts`
- [Repository Curation](https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/lib/curate.ts): data processing · `src/lib/curate.ts`
- [Cluster and Vertical Classifier](https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/lib/classifier.ts): classifier · `src/lib/classifier.ts`
- [Portfolio Aggregation](https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/lib/aggregate.ts): aggregation · `src/lib/aggregate.ts`

### Portfolio Exploration UI

- [Portfolio Overview](https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/components/Hero.tsx): view · `src/components/Hero.tsx`
- [Constellation Explorer](https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/components/PortfolioConstellation.tsx): interactive view · `src/components/PortfolioConstellation.tsx`
- [Repository Search and Filters](https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/src/components/Filters.tsx): filter controls · `src/components/Filters.tsx`

### Snapshot Refresh

- [Scheduled Snapshot Refresh](https://github.com/mizcausevic-dev/portfolio-constellation/blob/main/.github/workflows/refresh-snapshot.yml): workflow · `.github/workflows/refresh-snapshot.yml`

### Other components

- **Portfolio Visitor**: external actor
- **GitHub REST API**: external API
- **Scheduled Actions Runner**: external actor

## Connections

- Portfolio Visitor → Browser Entry: opens site
- Browser Entry → Dashboard Orchestration: mounts or hydrates
- Server Prerender → Dashboard Orchestration: renders HTML · Uses the baked snapshot; effects do not run during prerendering.
- Dashboard Orchestration → Bundled Snapshot: initializes from
- Dashboard Orchestration → Snapshot and Live Refresh: requests refresh · Requested after first paint; accepts a non-null result only when it is not smaller than the current set.
- Snapshot and Live Refresh → GitHub REST API: fetches repositories
- Snapshot and Live Refresh → Snapshot and Live Refresh: caches results · Reads and writes a six-hour browser local-storage cache.
- Dashboard Orchestration → Repository Curation: gets cleaned set
- Repository Curation → Cluster and Vertical Classifier: uses classification
- Dashboard Orchestration → Portfolio Aggregation: computes statistics
- Dashboard Orchestration → Portfolio Overview: supplies values
- Dashboard Orchestration → Constellation Explorer: supplies cluster stats
- Constellation Explorer → Dashboard Orchestration: updates platform filter
- Dashboard Orchestration → Repository Search and Filters: supplies filter state
- Scheduled Actions Runner → Scheduled Snapshot Refresh: starts workflow
- Scheduled Snapshot Refresh → GitHub REST API: refreshes repository list · The README documents refresh via gh api.
- Scheduled Snapshot Refresh → Bundled Snapshot: commits changes · Updated snapshot data is used by subsequent builds.