Noumenal Notes: Concise Dev Plan

Brand: Reason Studio; Noumenal Notes is the first blog post name and demo. critique.vania-novikau.me is the n8n agent endpoint used on that post page. Future product reason-studio.vania-novikau.me will let others wire in their own API keys, but it is not the priority now.

Core Experience

• Highlight-to-chat sidebar and floating trigger on the Noumenal Notes post.
• Context-aware answers (post content, highlighted passage, chat history, Kant corpus).
• Token-gated access: logged-in users with positive balance can chat; top-ups allowed at minimal amounts via Stripe and crypto, and balance is visible near account info after login.
• Future UX tools (architectonic concept map, reading paths, Kant vs. X comparisons, Socratic quiz) are part of the post and treated as a main priority to ship with it.
• Users can chat privately or invoke the agent in public comments under the post; agent replies inline to keep the discussion threaded.

Architecture Snapshot

• WordPress agent bridge plugin (more general than a single route): enqueues assets, exposes REST endpoint(s) to call n8n, handles auth and balance checks, and renders history. Needs a billing/auth plugin stack (to be selected) to create accounts, bill, and allow top-ups.
• Backend: n8n in a container with webhook(s); Postgres/PGVector for corpus; separate Postgres for chat history; OpenAI for completion calls.
• History: plugin writes/reads chat sessions from Postgres (history DB) so the bot and UI can reuse context and users can browse past conversations.
• Payments: Stripe/crypto top-ups; WP side deducts per interaction; webhook credits balances.
• Data flow: browser highlight -> REST POST -> auth/token check -> n8n (RAG + LLM) -> usage returned -> tokens deducted -> response rendered (private chat UI or public comment reply).

Diagram

graph TD
    User([User / Reader])
    Stripe["Stripe & Crypto Payments"]
    OpenAI([OpenAI API])
    History[(Postgres\nChat History)]

    subgraph "Frontend (critique.vania-novikau.me)"
        Browser["Browser / JS Widget"]
        Highlight["Text Highlight Event"]
        ChatUI["Sidebar Chat UI"]
        Comments["WP Comments Thread"]
    end

    subgraph "WordPress (Agent Bridge Plugin)"
        WPREST["REST Endpoints"]
        AuthCheck{"Is Logged In?"}
        TokenCheck{"Has Balance?"}
        TokenDeduct["Deduct Tokens"]
        Balance["Show Balance"]
        Billing["Billing/Auth Plugin Stack"]
    end

    subgraph "Backend (n8n + Postgres)"
        Webhook["n8n Webhook Node"]
        RAG["RAG / Vector Search"]
        PGVector[(PGVector\nKant Corpus)]
        LLMCall["OpenAI Request"]
    end

    User -->|Highlights Text| Highlight
    Highlight --> ChatUI
    User -->|Types Question| ChatUI
    ChatUI -->|POST /message| WPREST
    Comments -->|Invoke Agent| WPREST

    User -->|Top Up| Stripe
    Stripe -->|Webhook Credit| Billing
    Billing -->|Update Balance| Balance

    WPREST --> AuthCheck
    AuthCheck -->|Yes| TokenCheck
    AuthCheck -->|No| Error401["401 Unauthorized"]
    TokenCheck -->|Yes| Webhook
    TokenCheck -->|No| Error402["Request Top Up"]

    Webhook --> RAG
    RAG <-->|Query Embeddings| PGVector
    RAG --> LLMCall
    LLMCall <-->|Chat Completion| OpenAI
    LLMCall -->|Reply + Usage| Webhook

    Webhook -->|Store/Fetch History| History
    WPREST -->|Return Answer + History| ChatUI
    WPREST -->|Public Reply| Comments
    TokenDeduct -->|Update Balance| Balance

More detailed architecture diagram also lives at AI/noumenal/README.md in /root/AI/noumenal/README.md.

Delivery Phases

1. Infrastructure: DNS + WP install for critique.vania-novikau.me; n8n container reachable; Postgres (PGVector + chat history).
2. Plugin scaffold: agent bridge plugin (enqueue, REST routes, auth/balance hooks, history CRUD, UI render); select billing/auth plugin stack (open decision).
3. Frontend UI: sidebar/chat widget, highlight listener, comment-triggered agent replies, history viewer, fetch to REST API.
4. n8n + RAG: ingest corpus, build webhook workflow, wire to OpenAI, read/write history and usage.
5. Payments/tokens: Stripe + crypto top-ups, webhook crediting; WP handler deducts per message and surfaces balance in UI.
6. Platform extension (later): Reason Studio tenant model (user accounts, agent templates, user-provided API keys, webhooks for Telegram/WP/custom).
7. Terraform: introduce IaC for scalable infra and repeatable container/db provisioning.
8. Social/messenger connections: hook Telegram/other channels to the same n8n agent endpoints.