ghglance/docs/system-architecture.md

System Architecture

Runtime shape

One process, three phases: flag parsing → data fetch → SVG render.

┌───────────┐   ┌──────────────────┐   ┌─────────────────┐   ┌──────────────┐
│ flag / env│──►│  internal/github │──►│  internal/card  │──►│  output/*.svg│
│  parsing  │   │  (GraphQL only)  │   │  (pure render)  │   │   per theme  │
└───────────┘   └──────────────────┘   └─────────────────┘   └──────────────┘
                         ▲                       ▲
                         │                       │
                    api.github.com        internal/theme

No database, no cache, no background workers in CLI mode. Stateless CLI; Action runtime just sets environment variables + runs the binary. -serve switches the same binary into the long-running web UI described under Web UI mode.

A root context.Context is built in main.go with an overall deadline (-timeout, default 30m) and cancelled on SIGINT/SIGTERM. Every fetcher and HTTP request inherits it so a slow run aborts cleanly instead of draining the 6h Action budget.

Data-fetch sequence

github.Collect owns this sequence; the CLI and every web UI job call it, so the two paths cannot drift. Only the profile fetch is fatal; later stages report through CollectConfig.Warnf and leave partial data.

github.Collect(ctx, client, login, cfg)
  │
  ▼
FetchProfile(ctx, login, opts)
  │  profileQuery × N pages (owned repos, STARGAZERS desc, 100/page)
  │  ownerAffiliations = [OWNER] (+ ORGANIZATION_MEMBER when
  │    opts.IncludeOrgRepos; non-ADMIN org repos dropped client-side)
  │  yields: Profile.{identity, stars, forks, PRs, issues,
  │                   TopRepos, ReposByLanguage,
  │                   ContributionYears,
  │                   DailyContributions (last year),
  │                   TotalCommits (last year)}
  │
  ▼
FetchContributionsAllTime(ctx, profile, opts)
  │  contributionYearQuery × 4 quarters × len(ContributionYears)
  │  per quarter: totalCommitContributions +
  │            contributionCalendar.weeks +
  │            commitContributionsByRepository(maxRepositories: 100)
  │  quarters keep most windows under the 100-repo ceiling, which a
  │    year-wide window silently truncates at; a quarter that still
  │    saturates is re-queried per month for repos only (its days and
  │    totals are already folded in)
  │  yields: SeedRepos (deduped),
  │          DailyContributionsAllTime,
  │          TotalCommitsAllTime
  │
  ▼
FetchProductive(ctx, profile, SeedRepos[:cfg.TopRepos], loc, commitsPerRepo)  // 0 = no cap
  │  commitHistoryQuery × (#seeds × pages)
  │  per commit: t = committedDate in loc
  │              ProductiveAllTime[t.Hour]++
  │              WeekdayAllTime[t.Weekday]++  + language votes
  │              if t.After(yearAgo): Productive[t.Hour]++
  │                                   Weekday[t.Weekday]++ + language votes
  │  yields: Productive, Weekday, ProductiveAllTime, WeekdayAllTime,
  │          CommitsByLanguage, CommitsByLanguageAllTime
  │
  ▼
card.RenderAll(profile, theme, outDir)  ×  len(themes)   // caller's step

GraphQL queries

All three queries live in internal/github/queries.go.

Query	Purpose	Cost estimate
profileQuery	Profile identity + totals + owned repos + last-year calendar	1–10 calls (100 repos/page × ≤10 pages safety cap)
contributionYearQuery	Per-quarter calendar + seed list	4 calls per active year, +3 per saturated quarter
commitHistoryQuery	Authored commits on default branch	1 call per 100 commits per seed repo

Typical run (8 active years, 30 seed repos, avg 50 commits each):

• profile: 1 call
• quarter loop: 8 × 4 = 32 calls
• commit history: 30 × 1 = 30 calls
• ≈ 63 GraphQL calls, 0 REST calls

Attribution model

Language attribution for the "most commit language" card is byte-weighted:

for each repo R:
    total_bytes = Σ R.languages[*].bytes   // precomputed once per repo
    for each commit C in R:
        for each (lang, bytes) in R.languages:
            commits_by_lang[lang] += scaleFactor × bytes / total_bytes

Implementation in internal/github/productive.go:attributeCommit. The per-repo byte total is hoisted out of the commit loop so the hot path doesn't re-sum language edges for every commit. scaleFactor = 10_000 preserves fractional precision in int64 storage — percentages rendered in the card are unaffected by magnitude.

Known distortion: linguist excludes prose types (Markdown, AsciiDoc, reST) from byte counts. Blog-style repos with 95% Markdown and 5% JS still attribute all commits to JS. Future fix: per-commit REST file classification via -accurate-languages (see roadmap).

SVG generation

Each card produces a self-contained SVG with:

• Card frame (rounded rect, theme background, theme stroke + opacity)
• Title (top-left, theme title color)
• Content layer (chart elements, text, legend)

Shared primitives:

• renderDonutCard(title, stats, theme) — pie slices via polar arc math + legend with color swatches (top 7 entries, rest collapse into "Other"). Single-slice case (one language at 100%) renders as two concentric <circle> elements instead of an arc, since SVG's A command from point P back to P draws nothing.
• renderProductiveTime(title, hours, theme) — 24 bars + both axes + tick math from niceTicks
• renderWeekday(title, data, theme) — 7-bar day-of-week chart mirroring the productive-time layout; peak bar uses theme.Accent, others mixHex(Background, Accent, 0.55)
• renderHeatmap(title, days, theme) — 7×53 calendar grid with a 5-bucket intensity ramp synthesised from theme.Background → theme.Accent
• renderContributions(title, days, theme) — monthly aggregation, Catmull-Rom → cubic Bezier area path, two-sided Y axis

Chart-geometry invariants:

• niceTicks(max, 5) rounds the top tick up to the next step (last = ceil(max/step) × step), guaranteeing yMax ≥ dataMax — bar heights can never exceed chartH and collide with the title row.
• formatTick abbreviates ≥ 1000 to k / M / B so y-axis labels never exceed 4 characters (10000 → "10k", 1234567 → "1.2M"); keeps the left gutter ≤ 28 px for every profile.
• header() picks the largest title font in [11, 15] px at which the string fits in width − 24 at a 0.6 char-width estimate, so long titles like Commits by Weekday (last year, UTC+7.00) still fit the frame.

Catmull-Rom control-point math: for each segment P_i → P_{i+1},

C1 = P_i + (P_{i+1} - P_{i-1}) / 6
C2 = P_{i+1} - (P_{i+2} - P_i) / 6

Tension = 0.5 (d3's default).

Theme model

theme.Theme is a pure-data struct — no methods. Cards pull t.Background, t.Text, t.Title, t.Accent, t.Muted, t.Stroke, t.StrokeOpacity. The 65 palettes live in a map keyed by snake_case ID.

Light themes (default, github, nord_bright, etc.) use StrokeOpacity: 1 with a visible stroke color; dark themes often use StrokeOpacity: 0 or a stroke that blends into the background.

Failure modes

Fault	Behavior
Empty -user	Exit 2, usage printed
Unknown theme	Exit 2, suggests -list-themes
GraphQL 4xx/5xx	Error wrapped with HTTP status and truncated (UTF-8-safe) body
Primary rate limit (429 / 403 + remaining=0)	Sleep up to 5 min honoring Retry-After / X-RateLimit-Reset, retry once; longer windows surface as error
Per-year query returns nil user	Warn to stderr; other years still contribute
FetchProductive network error	Warn to stderr; partial data rendered
Unknown timezone	Warn to stderr; fall back to UTC
Overall timeout (-timeout) or Ctrl-C	ctx cancels in-flight requests; partial data may render
User with 0 commits	Card renders "No data available"

Web UI mode

ghglance -serve :8080 runs internal/web (stdlib net/http, html/template, embed; vanilla JS, no build step) instead of the one-shot CLI path.

POST /auth/start ─► validate ─► rate limit ─► pending sign-in (state, PKCE verifier; memory, 10 min)
                 ─► 302 github.com/login/oauth/authorize (scope from ticks, state, S256 challenge)
GET /auth/callback ─► state == cookie, single use ─► POST /login/oauth/access_token
                   ─► narrow options to granted scopes (wider than ticked: revoke, refuse)
                   ─► Queue (dedup per user) ─► -workers goroutines
                                                   │  token owner check, cooldown
                                                   ▼
                       github.Collect ─► Store.Publish (every theme)
                                                   │
GET /u/{user} ◄── meta.json + card list ◄──────────┘
GET /u/{user}/{theme}/{card}.svg ◄── os.Root read
job ends ─► DELETE api.github.com/applications/{client_id}/token

• Storage. <data>/<user> (lowercased login) is a symlink into <data>/.gen/<user>-<nanos>/, which holds <theme>/<card>.svg plus meta.json (generated time, options, public/private scope; never the token). Publish renders into a fresh generation directory, then renames a new symlink over the old one, so a reader sees the old set or the new set, never a partial one. Startup sweeps generations no link points at. Sets older than -retention (default 24h) are deleted at startup and hourly; a store mutex keeps that removal from racing a republish.
• Path safety. Logins are checked against GitHub's rule (alphanumerics and single hyphens, 1–39 chars) and themes and card names against the registered lists before any path is built; reads go through os.Root.
• Jobs. In-process queue, at most one queued or running job per user, -workers concurrent, -timeout each, capacity 64. SIGTERM stops the HTTP server, cancels running jobs and drops queued ones; nothing is published mid-render.
• Tokens. The server has no GitHub token of its own: every job runs on the token of the visitor's sign-in. GitHub folds every private contribution a token can see into totals and calendars, so repo filters alone cannot keep cards public. Each job first identifies its token (viewer query: login, a one-repo privacy: PRIVATE probe, and a classic token's X-OAuth-Scopes). Signed in as the target login, the job keeps the ticked scope and skips the cooldown; as anyone else it is refused if private-capable, otherwise forced to public scope under the cooldown. The token lives only on the job and is cleared when it ends.
• Sign in with GitHub (internal/web/oauth.go). OAuth App web flow, required: -serve exits at startup unless -oauth-client-id, -oauth-client-secret and -public-url are all set. Scopes come from the ticked options (read:user; repo for private; read:org on top for org repos). /auth/start parks the validated submission under a 256-bit random state (10-minute TTL, 1,000 entries max) and binds it to the browser with an HttpOnly, SameSite=Lax cookie on /, named __Host-ghglance_oauth and Secure when the public URL is https so a sibling subdomain cannot plant it (plain ghglance_oauth over http, a weaker binding). The callback compares state and cookie in constant time, consumes the entry, exchanges the code with the PKCE verifier (15 s timeout), drops options whose scope GitHub did not grant, revokes and refuses a token carrying scopes the ticks did not ask for (GitHub folds earlier grants into new tokens), and hands the token to the queue. The worker revokes it before it reports the job finished; Stop revokes the tokens of queued jobs it drops, and a callback whose job is not queued revokes at once. Revocation is best effort and logs only the status. GitHub endpoints come from OAuthConfig.WebURL/APIURL, so tests run against httptest. The page CSP adds GitHub's origin to form-action, since browsers check a form submission's redirect against it.
• Partial fetches. The web path runs github.Collect with Strict, so a failed all-time or commit-history stage fails the job, and a job whose deadline passed is failed even if the fetch returned. The CLI keeps rendering partial data with warnings.
• HTTP hardening. Strict CSP on pages, default-src 'none' + sandbox on SVGs, nosniff, 16 KiB form limit, http.CrossOriginProtection on the POSTs, per-client token bucket (burst 5, +1 per 2 min) keyed by IPv4 address or IPv6 /64, capped at 10,000 tracked clients.

Extension points

• New card: implement Card interface, add to allCards in card.go.
• New theme: add entry to themes map in theme.go.
• New fetcher mode (e.g., REST per-commit): add a new method on *Client, call from github.Collect, wire to new Profile fields.