feat(docs-site): exhaustive Astro + refraction-ui documentation

[iarunsaragadam]

Summary

Adds a full Astro static documentation site for elloloop/notify at docs-site/, mirroring elloloop/identity/docs-site — same @refraction-ui/astro AppShell, same astro-expressive-code chrome, same astro-pagefind search modal, same DocsLayout shape, same theme + global CSS. Branding strings retargeted to notify (GitHub repo, container image, package name).

35 rendered pages, all building clean under pnpm run build, with the search index populated by Pagefind.

File map

docs-site/
├── astro.config.mjs               site: "https://elloloop.github.io", base: "/notify"
├── package.json                   pnpm; astro 5.18.1, @astrojs/tailwind 5.1.5,
│                                  tailwindcss 3.4.19 (the matrix identity actually runs)
├── pnpm-lock.yaml
├── tailwind.config.mjs
├── tsconfig.json
└── src/
    ├── components/                lifted from identity, retargeted to notify
    │   ├── Breadcrumbs.astro
    │   ├── EditOnGitHub.astro
    │   ├── Footer.astro
    │   ├── GitHubBadge.astro
    │   ├── HeadingAnchors.astro
    │   ├── PrevNext.astro
    │   ├── SearchButton.astro
    │   ├── SearchModal.astro
    │   ├── TableOfContents.astro
    │   └── VersionPill.astro
    ├── data/
    │   ├── build-info.ts          last-updated stamps, edit-on-GitHub URLs, GitHub stars badge
    │   └── nav.ts                 nine sidebar sections; flat list drives breadcrumbs + prev/next
    ├── layouts/DocsLayout.astro
    ├── styles/global.css          verbatim from identity
    └── pages/
        ├── 404.astro
        ├── index.astro            landing
        └── docs/
            ├── introduction.astro
            ├── quickstart.astro
            ├── concepts/                       (6)
            │   ├── architecture.astro
            │   ├── channels-and-providers.astro
            │   ├── store-and-conformance.astro
            │   ├── realtime-engine.astro
            │   ├── auth-model.astro
            │   └── multi-tenancy.astro
            ├── installation/                   (4)
            │   ├── docker.astro
            │   ├── configuration.astro          every NOTIFY_* env var in one table
            │   ├── jwt-keys.astro               HS256 generation + rotation procedure
            │   └── store-setup.astro            memory / postgres / entdb walkthroughs
            ├── channels/                       (6)
            │   ├── email.astro
            │   ├── sms.astro
            │   ├── whatsapp.astro
            │   ├── web-push.astro
            │   ├── mobile-push.astro
            │   └── in-app.astro
            ├── store/                          (4)
            │   ├── memory.astro
            │   ├── postgres.astro
            │   ├── entdb.astro
            │   └── conformance.astro
            ├── api-reference/                  (1)
            │   └── grpc.astro                  every RPC + every enum + error-code table
            ├── operations/                     (2)
            │   ├── observability.astro
            │   └── shutdown.astro
            ├── deployment/                     (3)
            │   ├── docker.astro
            │   ├── kubernetes.astro
            │   └── github-actions.astro
            └── examples/                       (5)
                ├── send-notification.astro     cURL + Go + Python
                ├── subscribe-sse.astro         Connect-Web with reconnect backoff
                ├── register-push-token.astro   Web Push + Android/iOS round-trips
                ├── ack-notification.astro      AckNotification + AckDataChange
                └── multi-channel-fanout.astro  3 users x 3 channels, partial-failure semantics

Other changes

• .github/workflows/docs.yml — new sibling workflow. Builds the docs site on every PR (broken build = red check, can't merge). On pushes to main, additionally publishes the rendered dist/ to GitHub Pages.
• README.md — added a "Docs" section linking to the published site and to the local build commands.
• .gitignore — ignore docs-site/node_modules/, docs-site/dist/, docs-site/.astro/.

Content quality bar

Every page meets the brief's bar:

• Lede paragraph answering the title.
• "When you'd use this" / "When you'd care" paragraph.
• At least one complete, copy-pasteable code block — no // ... details elided. cURL flows are runnable as-is against a dev-mode container; Go / Python / TS recipes compile against the published generated stubs.
• Cross-links to related pages at the bottom.
• "Why this design" blockquote on the non-obvious decisions: caller-supplied notification IDs, in-app StatusPending for offline users, length-prefix-encoded composite_key, providers never auto-purging dead tokens, tenant always from the JWT (never the body), AckNotification ownership check returning NotFound (never PermissionDenied).

The seven high-value worked examples from the brief are all present and complete:

1. Quickstart — docker run (memory + dev mode) → cURL Notify → Connect-Web SSE handler.
2. Send from Go — full NotificationInternalServiceClient wrapper with X-Notify-Internal-Token.
3. Send from Python — Connect-Python with the same internal-token header.
4. Browser subscription — createConnectTransport + async generator + exponential-backoff reconnect.
5. Web Push end-to-end — service worker, PushManager subscribe, RegisterPushToken call.
6. FCM mobile push end-to-end — Android (Kotlin) + iOS (Swift) token registration, server-side Notify, UNREGISTERED handling.
7. Conformance for new store drivers — conformance.RunConformance snippet + ConcurrentCreate_SameKey_SingleWinner walked through.

Verification

cd docs-site
pnpm install            # ~5s
pnpm run build          # 35 pages built; pagefind indexed
pnpm run preview        # serves on http://127.0.0.1:4321/notify

Smoke check of the rendered site:

$ curl -fsS http://127.0.0.1:4321/notify/ | grep -oE '<title>[^<]*</title>'
<title>Introduction — notify Documentation</title>

$ curl -fsS http://127.0.0.1:4321/notify/docs/quickstart/ | grep -oE '<title>[^<]*</title>'
<title>Quick Start — notify Documentation</title>

$ curl -fsS -o /dev/null -w 'pagefind: HTTP %{http_code}\n' \
    http://127.0.0.1:4321/notify/pagefind/pagefind-entry.json
pagefind: HTTP 200

Notes for the reviewer

• Dependency matrix. identity's package.json lists astro@6.3.3 / @astrojs/tailwind@6.0.2 / tailwindcss@4.3.0, but identity's installed node_modules/ on disk actually runs astro@5.18.1 / @astrojs/tailwind@5.1.5 / tailwindcss@3.4.19 — their lockfile and installed deps are out of sync. I followed the working matrix; the newer one fails at build time with the Tailwind 4 PostCSS plugin error. If identity's docs-site gets re-bootstrapped against the newer matrix, this repo's docs-site/package.json should follow.
• GitHub Pages. The deploy job in .github/workflows/docs.yml assumes the repo has Pages enabled with the "GitHub Actions" source. If it isn't enabled yet, the PR check (build only) is still green; the deploy step on main will be skipped until Pages is toggled on.
• Pagefind. Indexes only article bodies (the layout uses data-pagefind-body on <article class="prose"> and data-pagefind-ignore on chrome elements). 35 pages indexed, ~quick lookup via the ⌘K modal.

DO NOT merge — leave it for principal review.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1091811e79

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Make the compose DSN match the bundled Postgres

In this docker-compose example, the db service uses the stock postgres:16 image and does not configure server TLS, but the notify DSN requires TLS with sslmode=require. Anyone copying this stack will have notify fail to connect to its own database unless they add cert/key setup to the Postgres service; for this in-network compose database the example should use sslmode=disable or document the missing TLS configuration.

Useful? React with 👍 / 👎.