# gurshaan17/p99 architecture

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

- Interactive diagram: https://gitdiagram.com/gurshaan17/p99
- Repository: https://github.com/gurshaan17/p99

## Overview

p99 is a daily production-incident diagnosis and learning site. Readers encounter a published incident, inspect symptoms, constraints, and telemetry, choose a diagnosis, then reveal the explanation, self-check their reasoning, and retain lessons; attempt state is stored locally. The archive and topic pages support discovery. Separate branches provide SEO/feed surfaces and email subscription/digest operations. Evidence is limited to the README and the supplied excerpts/SOURCE INDEX; some component-level and integration details are unsampled, so those links are omitted or documented rather than inferred.

Main entry points: [`lib/incidents.ts`](https://github.com/gurshaan17/p99/blob/main/lib/incidents.ts) (Publish-aware queries), [`app/q/[slug]/page.tsx`](https://github.com/gurshaan17/p99/blob/main/app/q/%5Bslug%5D/page.tsx) (Incident write-up), [`app/api/subscribe/route.ts`](https://github.com/gurshaan17/p99/blob/main/app/api/subscribe/route.ts) (Subscription endpoint), [`lib/email/send.ts`](https://github.com/gurshaan17/p99/blob/main/lib/email/send.ts) (Email rendering and sending)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Incident content"]
  node_incident_files["Incident records"]
  node_incident_registry["Incident registry<br/>[index.ts]"]
  node_incident_queries["Publish-aware queries<br/>[incidents.ts]"]
end

subgraph group_reader["Reader experience"]
  node_home["Daily incident<br/>[page.tsx]"]
  node_incident_page["Incident write-up<br/>[page.tsx]"]
  node_question_components["Diagnosis and reveal<br/>[incident.tsx]"]
  node_attempt_state["Answer and scoring state<br/>[attempts.ts]"]
  node_attempt_hook["Attempt state hook<br/>[useAttempt.ts]"]
end

subgraph group_discovery["Discovery and SEO"]
  node_archive_routes["Archive and topics<br/>[page.tsx]"]
  node_archive_ui["Archive presentation"]
  node_search_palette["Search and command palette"]
  node_seo_core["SEO page generation<br/>[pages.ts]"]
  node_seo_metadata["SEO metadata<br/>[metadata.ts]"]
  node_sitemap["Sitemap generation<br/>[sitemap.ts]"]
  node_feed_routes["RSS and llms feeds<br/>[route.ts]"]
end

subgraph group_email["Email operations"]
  node_signup["Subscription endpoint<br/>[route.ts]"]
  node_subscriber_store[("Subscriber records<br/>[route.ts]")]
  node_email_rendering["Email rendering and sending<br/>[send.ts]"]
  node_digest_cron["Daily digest job<br/>[route.ts]"]
  node_ses_service["Amazon SES<br/>[ses.ts]"]
end

subgraph group_platform["Publishing services"]
  node_redis[("Upstash Redis<br/>[redis.ts]")]
  node_revalidation["Scheduled revalidation<br/>[route.ts]"]
end

node_reader_actor(("Reader"))
node_feed_consumer(("Feed consumer"))
node_subscriber(("Email subscriber"))

node_incident_files -->|"registered in"| node_incident_registry
node_incident_registry -->|"queried by"| node_incident_queries
node_incident_queries -->|"supplies published incident"| node_home
node_reader_actor -->|"opens"| node_home
node_home -->|"opens full write-up"| node_incident_page
node_incident_queries -->|"resolves slug"| node_incident_page
node_incident_page -->|"renders incident sections"| node_question_components
node_incident_page -->|"supports attempt UI"| node_attempt_hook
node_attempt_hook -->|"reads and updates"| node_attempt_state
node_attempt_state -->|"persists local answers"| node_incident_page
node_incident_queries -->|"supplies published records"| node_archive_routes
node_archive_routes -->|"renders archive view"| node_archive_ui
node_reader_actor -->|"browses incidents"| node_archive_routes
node_incident_queries -->|"provides visible incidents"| node_search_palette
node_incident_queries -->|"builds incident SEO data"| node_seo_core
node_seo_core -->|"feeds page metadata"| node_seo_metadata
node_incident_queries -->|"supplies published URLs"| node_sitemap
node_incident_queries -->|"supplies published incidents"| node_feed_routes
node_feed_routes -->|"serves feeds"| node_feed_consumer
node_reader_actor -->|"subscribes"| node_signup
node_signup -->|"rate limits and stores"| node_redis
node_signup -->|"adds subscriber"| node_subscriber_store
node_signup -->|"sends welcome email"| node_email_rendering
node_digest_cron -->|"reads subscriber list"| node_redis
node_digest_cron -->|"sends daily digest"| node_email_rendering
node_email_rendering -->|"sends messages"| node_ses_service
node_email_rendering -->|"delivers email"| node_subscriber
node_revalidation -->|"refreshes publish data"| node_incident_queries
node_revalidation -->|"invalidates page output"| node_reader_actor

click node_incident_files "https://github.com/gurshaan17/p99/tree/main/content/incidents"
click node_incident_registry "https://github.com/gurshaan17/p99/blob/main/content/incidents/index.ts"
click node_incident_queries "https://github.com/gurshaan17/p99/blob/main/lib/incidents.ts"
click node_home "https://github.com/gurshaan17/p99/blob/main/app/page.tsx"
click node_incident_page "https://github.com/gurshaan17/p99/blob/main/app/q/%5Bslug%5D/page.tsx"
click node_question_components "https://github.com/gurshaan17/p99/blob/main/components/question/incident.tsx"
click node_attempt_state "https://github.com/gurshaan17/p99/blob/main/lib/attempts.ts"
click node_attempt_hook "https://github.com/gurshaan17/p99/blob/main/hooks/useAttempt.ts"
click node_archive_routes "https://github.com/gurshaan17/p99/blob/main/app/archive/page.tsx"
click node_archive_ui "https://github.com/gurshaan17/p99/tree/main/components/archive"
click node_search_palette "https://github.com/gurshaan17/p99/blob/main/components/shell/command-palette.tsx"
click node_seo_core "https://github.com/gurshaan17/p99/blob/main/lib/seo/pages.ts"
click node_seo_metadata "https://github.com/gurshaan17/p99/blob/main/lib/seo/metadata.ts"
click node_sitemap "https://github.com/gurshaan17/p99/blob/main/lib/seo/sitemap.ts"
click node_feed_routes "https://github.com/gurshaan17/p99/blob/main/app/rss.xml/route.ts"
click node_signup "https://github.com/gurshaan17/p99/blob/main/app/api/subscribe/route.ts"
click node_subscriber_store "https://github.com/gurshaan17/p99/blob/main/app/api/subscribe/route.ts"
click node_email_rendering "https://github.com/gurshaan17/p99/blob/main/lib/email/send.ts"
click node_digest_cron "https://github.com/gurshaan17/p99/blob/main/app/api/cron/daily-digest/route.ts"
click node_ses_service "https://github.com/gurshaan17/p99/blob/main/lib/ses.ts"
click node_redis "https://github.com/gurshaan17/p99/blob/main/lib/redis.ts"
click node_revalidation "https://github.com/gurshaan17/p99/blob/main/app/api/revalidate/route.ts"

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_incident_files,node_incident_registry,node_incident_queries toneBlue
class node_home,node_incident_page,node_question_components,node_attempt_state,node_attempt_hook toneAmber
class node_archive_routes,node_archive_ui,node_search_palette,node_seo_core,node_seo_metadata,node_sitemap,node_feed_routes toneMint
class node_signup,node_subscriber_store,node_email_rendering,node_digest_cron,node_ses_service toneRose
class node_redis,node_revalidation,node_reader_actor,node_feed_consumer,node_subscriber toneIndigo
```

## Components

### Incident content

- [Incident records](https://github.com/gurshaan17/p99/tree/main/content/incidents): `content/incidents`
- [Incident registry](https://github.com/gurshaan17/p99/blob/main/content/incidents/index.ts): `content/incidents/index.ts`
- [Publish-aware queries](https://github.com/gurshaan17/p99/blob/main/lib/incidents.ts): `lib/incidents.ts`

### Reader experience

- [Daily incident](https://github.com/gurshaan17/p99/blob/main/app/page.tsx): `app/page.tsx`
- [Incident write-up](https://github.com/gurshaan17/p99/blob/main/app/q/%5Bslug%5D/page.tsx): `app/q/[slug]/page.tsx`
- [Diagnosis and reveal](https://github.com/gurshaan17/p99/blob/main/components/question/incident.tsx): `components/question/incident.tsx`
- [Answer and scoring state](https://github.com/gurshaan17/p99/blob/main/lib/attempts.ts): `lib/attempts.ts`
- [Attempt state hook](https://github.com/gurshaan17/p99/blob/main/hooks/useAttempt.ts): `hooks/useAttempt.ts`

### Discovery and SEO

- [Archive and topics](https://github.com/gurshaan17/p99/blob/main/app/archive/page.tsx): `app/archive/page.tsx`
- [Archive presentation](https://github.com/gurshaan17/p99/tree/main/components/archive): `components/archive`
- [Search and command palette](https://github.com/gurshaan17/p99/blob/main/components/shell/command-palette.tsx): `components/shell/command-palette.tsx`
- [SEO page generation](https://github.com/gurshaan17/p99/blob/main/lib/seo/pages.ts): `lib/seo/pages.ts`
- [SEO metadata](https://github.com/gurshaan17/p99/blob/main/lib/seo/metadata.ts): `lib/seo/metadata.ts`
- [Sitemap generation](https://github.com/gurshaan17/p99/blob/main/lib/seo/sitemap.ts): `lib/seo/sitemap.ts`
- [RSS and llms feeds](https://github.com/gurshaan17/p99/blob/main/app/rss.xml/route.ts): `app/rss.xml/route.ts`

### Email operations

- [Subscription endpoint](https://github.com/gurshaan17/p99/blob/main/app/api/subscribe/route.ts): `app/api/subscribe/route.ts`
- [Subscriber records](https://github.com/gurshaan17/p99/blob/main/app/api/subscribe/route.ts): `app/api/subscribe/route.ts`
- [Email rendering and sending](https://github.com/gurshaan17/p99/blob/main/lib/email/send.ts): `lib/email/send.ts`
- [Daily digest job](https://github.com/gurshaan17/p99/blob/main/app/api/cron/daily-digest/route.ts): `app/api/cron/daily-digest/route.ts`
- [Amazon SES](https://github.com/gurshaan17/p99/blob/main/lib/ses.ts): `lib/ses.ts`

### Publishing services

- [Upstash Redis](https://github.com/gurshaan17/p99/blob/main/lib/redis.ts): `lib/redis.ts`
- [Scheduled revalidation](https://github.com/gurshaan17/p99/blob/main/app/api/revalidate/route.ts): `app/api/revalidate/route.ts`

### Other components

- **Reader**
- **Feed consumer**
- **Email subscriber**

## Connections

- Incident records → Incident registry: registered in
- Incident registry → Publish-aware queries: queried by (evidence: `lib/incidents.ts`)
- Publish-aware queries → Daily incident: supplies published incident (evidence: `app/page.tsx`)
- Reader → Daily incident: opens
- Daily incident → Incident write-up: opens full write-up (evidence: `app/page.tsx`)
- Publish-aware queries → Incident write-up: resolves slug (evidence: `app/q/[slug]/page.tsx`)
- Incident write-up → Diagnosis and reveal: renders incident sections (evidence: `app/q/[slug]/page.tsx`)
- Incident write-up → Attempt state hook: supports attempt UI
- Attempt state hook → Answer and scoring state: reads and updates (evidence: `hooks/useAttempt.ts`)
- Answer and scoring state → Incident write-up: persists local answers
- Publish-aware queries → Archive and topics: supplies published records (evidence: `app/archive/page.tsx`)
- Archive and topics → Archive presentation: renders archive view (evidence: `app/archive/page.tsx`)
- Reader → Archive and topics: browses incidents
- Publish-aware queries → Search and command palette: provides visible incidents
- Publish-aware queries → SEO page generation: builds incident SEO data (evidence: `lib/seo/pages.ts`)
- SEO page generation → SEO metadata: feeds page metadata (evidence: `app/q/[slug]/page.tsx`)
- Publish-aware queries → Sitemap generation: supplies published URLs (evidence: `lib/seo/sitemap.ts`)
- Publish-aware queries → RSS and llms feeds: supplies published incidents (evidence: `app/rss.xml/route.ts`)
- RSS and llms feeds → Feed consumer: serves feeds (evidence: `app/rss.xml/route.ts`)
- Reader → Subscription endpoint: subscribes
- Subscription endpoint → Upstash Redis: rate limits and stores (evidence: `app/api/subscribe/route.ts`)
- Subscription endpoint → Subscriber records: adds subscriber (evidence: `app/api/subscribe/route.ts`)
- Subscription endpoint → Email rendering and sending: sends welcome email (evidence: `app/api/subscribe/route.ts`)
- Daily digest job → Upstash Redis: reads subscriber list (evidence: `app/api/cron/daily-digest/route.ts`)
- Daily digest job → Email rendering and sending: sends daily digest (evidence: `app/api/cron/daily-digest/route.ts`)
- Email rendering and sending → Amazon SES: sends messages (evidence: `lib/email/send.ts`)
- Email rendering and sending → Email subscriber: delivers email
- Scheduled revalidation → Publish-aware queries: refreshes publish data (evidence: `app/api/revalidate/route.ts`)
- Scheduled revalidation → Reader: invalidates page output
