The Harithsa Notes

Technical guide

The public notebook and the publishing workspace share an Astro and TypeScript application. GitHub Pages builds this documentation as a separate static site.

Follow a request

Firebase Hosting serves the versioned web assets. Supported application routes are rewritten to a pinned second-generation Firebase HTTP Function. The Astro server renders public pages from the published content projection and handles search, publishing, and content API requests.

Firestore holds drafts, immutable revisions, published projections, invitations and the publication audit outbox. Firebase Storage holds public artwork and uploaded media. The application authorizes protected files before serving them.

Separate public and invited content

Firebase Auth verifies Google identity. The application authorizes workspace operations for the site owner and reader access for active invitees. Private posts and their media are excluded from public feeds, sitemaps and snapshots. Preview uses a separate data namespace for acceptance tests.

Integrate through the Content API

Use the versioned /api/v1 endpoints with a collection-scoped Bearer key from Developer Settings. OpenAPI and Swagger show per-collection schemas, media operations, revision checks and publish actions.

  1. If needed, upload media with multipart POST /api/v1/media and keep the returned URL.
  2. Create a draft under /api/v1/entries/{collection}. Read the current draft before replacing its complete data with PUT and expectedRevision.
  3. Publish the saved revision with the publish endpoint and an Idempotency-Key. Reuse that key when retrying the same publish action. A stale revision returns HTTP 409.

Run locally

Use Node.js 24 and Python 3.12. In a checkout, run npm ci, then npm run dev and open http://127.0.0.1:4321. Local public pages use checked-in content snapshots. For CMS checks, install Java 21 for the Firebase emulator and use the test workflow with fictional data.

  1. Run npm run check, npm run build and npm test for the public app.
  2. Run npm run test:cms for Firebase-backed contract tests.
  3. Run python scripts/build_public_docs.py to validate the Pages build and its relative links.

Observe the app

Dynatrace receives operational telemetry from the runtime. Publication writes include an audit event in the same transaction. Request diagnostics use safe fields. Browser analytics are opt-in on public pages and stay disabled in the private reading room and Workspace.

Related links