Note

    architecture-overview

    End-to-end architecture for ingestion, enrichment, admin, and taxonomy

    Dates

    Created
    Not recorded
    Last updated
    Not recorded

    Document Metadata

    • title: Architecture Overview
    • description: End-to-end architecture for ingestion, enrichment, admin, and taxonomy
    • status: evolving
    • lastUpdated: "2026-03-22 12:34 ET (America/New_York)"
    • owner: Engineering

    Architecture Overview ## Runtime Stack - App: Next. js App Router (app/) - Auth: Better Auth (lib/auth/) with app profile table users - Datab

    Architecture Overview

    Runtime Stack

    • App: Next.js App Router (app/)
    • Auth: Better Auth (lib/auth/) with app profile table users
    • Database: Neon Postgres via Drizzle (db/neon/)
    • AI: AI SDK with OpenAI/Anthropic model selection
    • Storage: Cloudflare R2 for uploaded/normalized images (lib/storage/r2.ts)

    Main Domains

    • Submission and enrichment: app/(public)/submit-new/
    • Seed enrichment pipeline: db/seed/src/
    • Admin and moderation: app/(admin)/admin/
    • Taxonomy system: taxonomy/spec.ts, taxonomy_terms, product_taxonomy, taxonomy_synonyms
    • Ownership claims: app/api/claims/
    • Route-family orientation: app/README.md

    Shared Runtime Domains

    • lib/auth/ for Better Auth client/server/session helpers
    • lib/blog/ for blog publishing helpers and feed generation
    • lib/editorial/ for WhatsApp intake, retrieval, draft-contract, and review-state helpers
    • lib/resources/ for resource feeds, contracts, contacts, URL helpers, and resource-card policy helpers
    • lib/site/ for SEO config and analytics helpers
    • lib/media/ for placeholder-image helpers
    • lib/storage/ for object-storage upload helpers
    • Remaining generic helpers stay intentionally flat unless a clearer domain boundary emerges

    Editorial Workflow Boundary

    • The shipped blog now includes a first governance slice beyond the original publishing workflow:
      • post-level review-gate fields on blog_posts
      • reviewer decision linkage into editorial_review_decisions
      • admin review-state/byline controls
      • publish-time review-gate enforcement in blog server actions
    • Broader editorial-governance targets from 3036 still remain downstream:
      • provenance summary
      • richer brief/draft linkage on blog posts
      • deeper review/audit views and downstream editorial workflow ownership
    • When adding future editorial work, extend the existing blog/admin surfaces rather than creating a parallel publishing stack by default.

    Data Flow (High Level)

    1. Resource arrives through user submission or seed crawler.
    2. AI enrichment normalizes metadata and taxonomy candidates.
    3. Product row is persisted/upserted.
    4. Taxonomy terms are linked through product_taxonomy.
    5. Admin tools review and curate records, claims, and taxonomy.

    Authorization Model

    • middleware.ts protects route families by session cookie presence.
    • Privileged admin behavior is enforced by users.is_admin checks in server actions/layout.
    • First app user profile is auto-promoted to admin in ensureAppUserProfile.

    Operational Automation Surface

    • CI workflow for docs sync/build: .github/workflows/docs-site-sync.yml
    • CI workflow for performance suite: .github/workflows/perf.yml
    • No built-in app cron jobs were found; recurring operations are script/CI-driven.

    Where to Go Next

    Provenance