Design RAG companion web app for The Arena campaign

[Copilot]

Design a React-based companion web app that allows players to query campaign content via conversational AI while preventing spoilers from unrevealed sessions and future plot arcs.

Architecture Documents

6 comprehensive design documents (~165KB, 3,871 lines):

• RAG_COMPANION_APP_README.md - Navigation hub
• RAG_COMPANION_APP_SUMMARY.md - Executive summary, quick reference
• RAG_COMPANION_APP_DESIGN.md - Complete architectural specification (main)
• RAG_COMPANION_APP_DIAGRAMS.md - Visual architecture diagrams, user flows
• CONTENT_METADATA_SPEC.md - YAML frontmatter specification for content visibility
• RAG_COMPANION_APP_FAQ.md - Common questions, troubleshooting

Technical Stack

Frontend: React 18+, TypeScript, Vite, Tailwind CSS, shadcn/ui, TanStack Query, Zustand
Backend: Node.js 20+, Fastify/Express, PostgreSQL, Prisma ORM, Redis
AI/ML: Pinecone vector DB, OpenAI text-embedding-3-small, GPT-4 Turbo
Hosting: Vercel (frontend), Railway/Render (backend), GitHub Actions (sync)

Content Visibility System

Three-tier access control via YAML frontmatter:

---
visibility: public           # All authenticated players
revealed: true              # Must be true for public access
content_type: session       # session | mechanic | npc | character | environment | idea
session_number: 3
participants: [imwe, torgana, orion]
tags: [combat, aerial, crowd-favor]
---

• Public: Revealed sessions, published mechanics (all players)
• Player-Specific: Character notes, patron relationships (owner + GM only)
• Private: Future sessions, unrevealed content (GM only, never indexed)

RAG Query Pipeline

1. Classify query intent and extract entities
2. Apply visibility filters based on user permissions
3. Generate query embedding (OpenAI)
4. Vector similarity search (Pinecone, top-k with metadata filtering)
5. Assemble context from retrieved chunks
6. Generate response with GPT-4 using Arena-themed system prompt
7. Format with citations, wiki-links, and follow-up suggestions

Target response time: <3 seconds

Implementation Roadmap

Phase 1 (Weeks 1-3): Infrastructure, RAG pipeline, basic chat UI
Phase 2 (Weeks 4-5): Authentication, session browser, character dashboard, mechanics reference
Phase 3 (Week 6+): Deployment, testing, iteration

Total: 6 weeks to MVP

Cost Estimates

MVP: $15-70/month (Vercel free, Railway $5-20, Pinecone free, OpenAI $10-50)
Production (100 users): $210-330/month

Open Questions

• Character access model: all characters visible or owner-only?
• Session reveal workflow: manual GM approval or automatic after date?
• Voice/tone: strict announcer style or allow neutral mode?
• Mobile: responsive web app sufficient or native app needed?
• Integrations: Discord bot, VTT hooks priority?

Next Steps

1. Review design documents
2. Answer open questions
3. Set up hosting accounts (Vercel, Railway, Pinecone)
4. Generate API keys (OpenAI, GitHub)
5. Begin Phase 1 implementation

---

Note: Design-only deliverable per issue request. No code implementation included.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>RAG web companion app</issue_title>
<issue_description>This is a task to design a companion webapp adjacent to the sessions:
I'm interested in deploying a web app that would predominantly be a text interface where players could ask for summaries of sessions or character notes or what kind of crowd favor they could use to achieve a specific aim. The key thing is I would want them to have access to some components of the GitHub repo but not all of them I.E future sessions and plot arcs that haven't been made public yet

Design & plan a companion web app that would achieve these goals. Do not write any code, just the architectural designs and features.

Something in React would be best. </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes RAG web companion app #21

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.