/
├── app/                    # Next.js App Router
├── components/             # React components
├── content/                # Nextra MDX documentation (served at /docs)
├── hooks/                  # TanStack Query hooks + utility hooks
├── lib/                    # All business logic, no React
├── public/                 # Static assets
├── stores/                 # Zustand state stores
├── supabase/               # Database migrations
├── types/                  # TypeScript types
└── example.env             # Template for .env.local

app/
├── [organization]/         # Org-scoped pages
│   ├── leaderboards/       # Leaderboard views + scoring preset editor
│   ├── analytics/          # Analytics dashboard (mostly stubbed)
│   └── teams/              # Team management (Coming Soon)
├── account/                # Signed-in user account page
├── api/                    # ALL backend API route handlers
│   ├── auth/               # OAuth flow, session endpoints
│   ├── install/            # GitHub App install flow
│   ├── webhooks/           # GitHub webhook receiver
│   └── [org]/              # Org-scoped API routes
│       ├── leaderboard/    # score, sync, recompute, scoring-rules
│       ├── organization/   # mass-invite, summary
│       ├── repository/     # analytics
│       └── teams/          # members
├── docs/                   # Nextra docs rendering
│   ├── layout.tsx          # Docs layout (Nextra Layout + navbar + footer)
│   └── [[...mdxPath]]/     # Catch-all page renderer for MDX files in content/
├── error.tsx               # Global error boundary
├── layout.tsx              # Root layout
├── not-found.tsx           # 404 page
└── page.tsx                # Landing page

components/
├── auth/                   # Sign-in button, error banner
├── layout/                 # Header, footer, shell, sidebar
├── leaderboards/           # Leaderboard tables, filters, scoring UI
├── organization/           # Mass invite form, team/role management UI
├── analytics/              # Analytics views (mostly placeholder)
└── ui/                     # shadcn/ui re-exports

hooks/
├── queries/                # TanStack Query useQuery hooks
├── mutations/              # TanStack Query useMutation hooks
├── query-keys.ts           # Centralized query key factory
├── use-auth-session.ts     # Session hook (wraps GET /api/auth/session)
└── use-mobile.ts           # Mobile breakpoint detection

lib/
├── auth/
│   └── server/             # OAuth flow, session CRUD, crypto, cookie helpers, installation auth
├── github/
│   ├── client-factory.ts           # Octokit factories (App singleton, installation token)
│   ├── create-leaderboard-octokit.ts  # Install-first, user-fallback strategy
│   ├── fetch-graphql.ts            # fetchOrgScoringDataGraphQL, fetchOrgTeamsDataGraphQL
│   ├── graphqlProxy.ts             # executeGithubGraphql (public proxy executor)
│   ├── graphql-response-cache.ts   # LRU + Redis cache for GraphQL responses
│   ├── ingest-limits.ts            # Pagination caps and concurrency limits
│   ├── operations/registry.ts      # USER_GITHUB_GRAPHQL_OPERATIONS + OPERATION_QUERY_FALLBACKS
│   └── queries/                    # Server-side ingest query strings (bypass allowlist)
├── leaderboard/
│   ├── pipeline.ts                 # recomputeLeaderboard, serveLeaderboard, refreshLeaderboardInBackground
│   ├── ingest.ts                   # runIngest()
│   ├── ingest-freshness.ts         # evaluateIngestFreshness, 24h cooldown logic
│   ├── score.ts                    # scoreActivePresetForEntity, scoreRemainingEntityTypes
│   ├── serve.ts                    # serveLeaderboard, computeCustomDateRange
│   ├── redis-cache.ts              # Snapshot cache (24h TTL)
│   ├── request-cache.ts            # Memory LRU (30s) + response cache (24h)
│   ├── cache-key.ts                # Cache key generation helpers
│   ├── resolve-installation.ts     # resolveInstallationForOrganization
│   └── time-range.ts               # getDateRangeForScoreTimePeriod
├── scoring/
│   ├── engine.ts                   # computeScores, computeSignalScore, buildLeaderboard
│   ├── aggregate.ts                # aggregateByRepository, aggregateByTeamSignals
│   ├── normalize.ts                # normalizeGitHubData (GitHub API response → Signal[])
│   ├── diminishing.ts              # diminishingValue formula
│   ├── rules.ts                    # defaultScoringRuleset()
│   └── index.ts                    # Barrel
├── supabase/               # DB repositories, one file per domain
│   ├── leaderboard-db.ts           # Leaderboard read/write (largest file)
│   ├── signals.ts                  # Signal upsert logic
│   ├── installation-repository.ts  # Installation CRUD
│   ├── organization-repository.ts  # Org CRUD
│   ├── repo-cache.ts               # Repository cache
│   ├── team-cache-repository.ts    # Team cache
│   ├── user-repository.ts          # User CRUD
│   ├── ingest-state.ts             # Ingest lock/state management
│   └── server.ts                   # Supabase server client factory
├── analytics/              # rollups.ts — type definitions only, no queries
├── api/                    # server.ts — requireApiSession, apiError, parseJsonBody
├── cache/                  # redis.ts — Upstash REST client, redisPatternDel
├── constants/              # time.ts — SCORE_TIME_PERIODS, INGEST, CACHE constants
├── env/                    # index.ts — @t3-oss/env-nextjs config + lazy proxies
├── errors.ts               # Error → human-readable message mapping
├── organization/           # Org helper utilities
├── schemas/                # Zod schemas for API request validation
└── utils.ts                # cn() — clsx + tailwind-merge

stores/
├── auth-store.ts           # session: AuthSession | null
├── workspace-store.ts      # selectedTeam, dateRange
├── leaderboard-store.ts    # leaderboardType, selectedRepository, selectedTeam, scoringRules
├── analytics-store.ts      # activeView, selectedRepository, selectedContributor
└── url-params-store.ts     # Per-route URL param cache

types/
├── auth/                   # session.ts (SessionView omits githubToken), state.ts
├── api/                    # installations, leaderboards, auth, sync, mass-invite
├── db/                     # All DB table shapes as TS interfaces
├── scoring/                # rules, leaderboard, aggregate, graphql, signals, presets
├── github/                 # installation.ts, teams.ts
└── installations/          # snapshot.ts