NovaDocs

NovaDocs is a multi-workspace document assistant. Upload text, Markdown, or PDF files into isolated workspaces, then ask questions grounded in your own content. Answers include citations, honest refusals when the corpus does not support a claim, and optional tools to save tasks or post Slack summaries.

What it does

• Workspaces — Separate knowledge bases per project; the backend enforces ownership on every API call.
• Document ingestion — Upload .txt, .md, or .pdf; content is chunked, embedded (Gemini), and stored in Supabase Postgres with pgvector.
• Semantic search — Search filenames and document content from the dashboard top bar.
• RAG chat — Retrieval-augmented chat with citation chips; refuses when context is insufficient.
• Tool calling — save_task (task board) and send_slack_summary (Slack webhook), with audit logs and prompt-injection defenses.
• Dashboard — Stats, recent documents, conversations, tasks, and a unified history view (documents + chat + tool-call log).

Architecture

Layer	Technology
Frontend	Next.js 16 (App Router), Tailwind, Supabase Auth (SSR)
Backend	FastAPI, Python 3.12+
Database	Supabase Postgres + pgvector
LLM & embeddings	Google Gemini (gemini-2.5-flash, gemini-embedding-001)
Notifications	Slack incoming webhook (optional)

The browser talks only to the FastAPI backend for workspace data, documents, search, and chat. The backend uses the Supabase service role key and validates the user's JWT on each request.

Prerequisites

• Node.js 20+
• Python 3.12+
• A Supabase project (Auth + Postgres + pgvector)
• A Google AI Studio API key for Gemini

Run locally

1. Supabase setup

1. Create a Supabase project and enable Email auth (or OAuth providers you plan to use).
2. Enable the pgvector extension in the SQL editor: create extension if not exists vector;
3. Apply schema migrations. Helper scripts exist under backend/scripts/ (e.g. apply_match_chunks.py, apply_tasks_tool_calls.py) when DATABASE_URL or SUPABASE_ACCESS_TOKEN is set; otherwise run the SQL referenced in those scripts via the Supabase SQL editor.
4. (Optional) Create a public Storage bucket named avatars if you want profile photo uploads in Settings.

2. Backend

cd backend
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

Copy environment variables (see .env.example) into backend/.env.local:

cp ../.env.example .env.local
# Edit .env.local — set SUPABASE_*, GEMINI_API_KEY, FRONTEND_URL=http://localhost:3000

Start the API:

uvicorn main:app --reload --host 0.0.0.0 --port 8000

Health check: http://localhost:8000/health

3. Frontend

cd frontend
npm install

Create frontend/.env.local with the frontend section from .env.example:

NEXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
NEXT_PUBLIC_API_URL=http://localhost:8000

Start the dev server:

npm run dev

Open http://localhost:3000, sign up / sign in, create a workspace, upload a document, and chat.

Environment variables

Variable	Where	Required	Description
SUPABASE_URL	Backend	Yes	Supabase project URL
SUPABASE_SERVICE_KEY	Backend	Yes	Service role key (server only)
GEMINI_API_KEY	Backend	Yes	Gemini API key for chat and embeddings
FRONTEND_URL	Backend	Yes	Allowed CORS origin (e.g. http://localhost:3000 or your Vercel URL)
SLACK_WEBHOOK_URL	Backend	No	Slack incoming webhook for send_slack_summary
DATABASE_URL	Backend	No	Postgres URL for migration helper scripts
NEXT_PUBLIC_SUPABASE_URL	Frontend	Yes	Same Supabase URL as backend
NEXT_PUBLIC_SUPABASE_ANON_KEY	Frontend	Yes	Supabase anon/public key
NEXT_PUBLIC_API_URL	Frontend	Yes	Backend base URL (no trailing slash)

See .env.example for a copy-paste template with no real secrets.

Deployment

The app is deployed as two services:

Service	Platform	Role
Frontend	Vercel	Next.js UI
Backend	Render	FastAPI API

Replace the placeholder URLs below with your own Vercel and Render service URLs.

Frontend — Vercel

1. Import the repository in Vercel.

2. Set Root Directory to frontend.

3. Framework preset: Next.js (default build: npm run build).

4. Add environment variables:

   Name	Value
   NEXT_PUBLIC_SUPABASE_URL	Your Supabase project URL
   NEXT_PUBLIC_SUPABASE_ANON_KEY	Supabase anon key
   NEXT_PUBLIC_API_URL	https://your-api.onrender.com

5. Deploy. Note the production URL (e.g. https://novadocs.vercel.app).

Backend — Render

1. Create a Web Service on Render and connect the repository.

2. Set Root Directory to backend.

3. Build command: pip install -r requirements.txt

4. Start command: uvicorn main:app --host 0.0.0.0 --port $PORT

5. Add environment variables:

   Name	Value
   SUPABASE_URL	Your Supabase project URL
   SUPABASE_SERVICE_KEY	Supabase service role key
   GEMINI_API_KEY	Gemini API key
   FRONTEND_URL	Your Vercel URL (e.g. https://novadocs.vercel.app)
   SLACK_WEBHOOK_URL	(optional) Slack webhook

6. Deploy. Note the service URL (e.g. https://novadocs-api.onrender.com).

Wire services together

1. Set NEXT_PUBLIC_API_URL on Vercel to your Render backend URL.
2. Set FRONTEND_URL on Render to your Vercel frontend URL (used for CORS).
3. In Supabase Authentication → URL configuration, add your Vercel URL to Site URL and Redirect URLs (e.g. https://your-app.vercel.app/**).

Redeploy both services after changing environment variables.

Tests

From backend/ with the virtualenv active and API running locally:

python scripts/test_tool_authorization.py   # Prompt-injection gate (no API/Gemini)
python scripts/test_ingestion_idempotency.py
python scripts/test_retrieval_isolation.py  # Workspace isolation for search
python scripts/test_rag_chat.py             # Grounded chat + refusal
python scripts/test_tool_calling.py         # Tasks, Slack, injection scenarios

Project layout

MW-Document-Assistant/
├── frontend/          # Next.js app (Vercel)
├── backend/           # FastAPI app (Render)
│   ├── main.py
│   ├── routers/
│   ├── services/
│   └── scripts/       # Integration tests & migration helpers
├── .env.example       # Environment template
└── README.md

Security notes

• Retrieved document text is treated as untrusted data, not instructions.
• Tool calls (save_task, send_slack_summary) require explicit user intent in the chat message; document-injected commands are blocked server-side.
• Workspace boundaries are enforced in the backend via get_owned_workspace on every workspace_id route.