You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Wrote the project README with overview, architecture diagram, setup, env
reference, the document and RAG pipelines, API examples, security notes and a
roadmap. Added an MIT license and a screenshots folder for readme images.
Moved the internal docs folder out of version control by gitignoring it, since
those are planning notes rather than part of the published project.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
DOC-007-AI is a production-style SaaS RAG (Retrieval-Augmented Generation) platform. Companies upload policies, SOPs, contracts, reports, and manuals; team members ask natural-language questions; the AI answers **only** from the uploaded documents and includes citations (document name, page, and source snippet). If the answer isn't in the documents, it says so instead of hallucinating.
21
+
DOC-007-AI is a production-style **RAG (Retrieval-Augmented Generation)** SaaS. Teams upload policies, SOPs, contracts, reports, and manuals; members ask natural-language questions; the AI answers **only** from the uploaded documents and returns citations (document name, page, and a source snippet). If the answer isn't in the documents, it says so instead of making something up.
22
+
23
+
It's built as a real product, not a demo: multi-tenant workspaces with strict isolation, role-based access, an asynchronous document-processing pipeline with a visible status state machine, and a swappable AI-provider layer.
15
24
16
25
## The problem it solves
17
26
18
-
Teams drown in documents, and generic chatbots hallucinate. DOC-007-AI gives teams **grounded, verifiable, workspace-isolated** answers from their own knowledge base — with the access control, audit trail, and processing pipeline a real business needs.
27
+
Teams drown in documents, and generic chatbots hallucinate. DOC-007-AI gives teams **grounded, verifiable, workspace-isolated** answers from their own knowledge base — with the access control, processing pipeline, and audit trail a business actually needs.
- 🏢 **Multi-tenant isolation** — enforced at the SQL layer **and**the vectorstore (every search is workspace-filtered); cross-tenant requests return `404`, not `403`, so existence isn't leaked
- 💬 **Grounded Q&A with citations** — answers cite document, page, and snippet; a confidence/coverage indicator; a strict "not found in your documents" fallback
37
+
- 🛡️ **Prompt-safety layer** — grounded system prompt; retrieved chunks are treated as untrusted data (prompt-injection defense), never as instructions
38
+
- 🔌 **Swappable providers** — OpenRouter (LLM) + OpenAI (embeddings), each with a deterministic **mock** so the whole app runs and tests without any API key
**Backend layering is enforced:** thin routers → services (business logic) → `rag/` (extraction · chunking · embeddings · vector store · retrieval · prompt · answer) and `providers/` (LLM + embeddings). No business logic or LLM calls live in routers.
# 2. Bring up the full stack (postgres, redis, qdrant, api, worker, web)
74
92
docker compose up --build
75
93
76
-
# 3. Open
77
-
# Frontend: http://localhost:3000
78
-
# API docs: http://localhost:8000/docs
79
-
# Health: http://localhost:8000/healthz
94
+
# 3. Apply database migrations (first run)
95
+
docker compose exec api alembic upgrade head
96
+
97
+
# 4. Open
98
+
# App: http://localhost:3000
99
+
# API docs: http://localhost:8000/docs
80
100
```
81
101
82
-
Database migrations (run once the stack is up):
102
+
Register an account, create a workspace, upload a document, watch it reach **Ready**, then ask questions on the Chat page.
83
103
84
-
```bash
85
-
docker compose exec api alembic upgrade head
86
-
```
104
+
> **No API keys?** The app still runs end to end using built-in **mock** providers — uploads process and the UI works — but answers will return the "not found" fallback because mock embeddings aren't semantically meaningful. Add real keys for genuine grounded answers.
87
105
88
-
### Local dev without Docker (API)
106
+
##Environment variables
89
107
90
-
```bash
91
-
cd apps/api
92
-
python -m venv .venv &&. .venv/Scripts/activate # Windows
93
-
pip install -e ".[dev]"
94
-
uvicorn doc007.main:app --reload
108
+
See [`.env.example`](.env.example) for the full, documented list. The important ones:
**API keys are server-side only and are never exposed to the frontend.**
122
+
123
+
## Document processing flow
124
+
125
+
```
126
+
upload → validate (type + size) → store file → row created (status=uploaded) → enqueue
127
+
worker: extracting → chunking → embedding → ready (failures → failed, with the error)
95
128
```
96
129
97
-
### Local dev without Docker (Web)
130
+
The status is persisted at each step so the UI can follow progress live, and the pipeline is idempotent (reprocess clears prior chunks/vectors first).
131
+
132
+
## RAG pipeline
133
+
134
+
**Query:** embed the question → Qdrant search filtered by `workspace_id` (top-k) → **guardrail** (if the best match is below the relevance threshold, return "not found" without calling the LLM) → build a safe prompt → LLM → parse `[n]` citations → map back to source chunks → persist conversation, messages, and citations.
135
+
136
+
**Prompt safety:** grounding and citation rules live in the system role. Retrieved chunks are wrapped in a `<context>` block and explicitly marked as untrusted reference data, so document content can never override the instructions (prompt-injection defense). Document text never enters the system role.
137
+
138
+
## API
139
+
140
+
Interactive docs at `http://localhost:8000/docs`. A minimal flow with `curl`:
-d '{"question":"How many vacation days do we get?"}'
103
161
```
104
162
105
-
## Environment variables
163
+
## Security notes
106
164
107
-
See [`.env.example`](.env.example) for the full, documented list. Key ones: `DATABASE_URL`, `REDIS_URL`, `QDRANT_URL`, `VECTOR_DIM`, `JWT_SECRET_KEY`, `OPENROUTER_API_KEY`, `OPENAI_API_KEY`. **API keys are server-side only and never exposed to the frontend.**
165
+
-**Tenant isolation** at three layers: workspace-scoped SQL queries, a mandatory `workspace_id` filter on every Qdrant search, and membership checks on every request (returning `404` to avoid leaking existence).
166
+
-**Prompt-injection defense:** retrieved document text is treated as untrusted data, never as instructions.
167
+
-**File validation** by type/extension and size; **argon2id** password hashing; JWT access + refresh.
168
+
- API keys are **server-side only**; secrets are never committed (`.env` is gitignored, `.env.example` documents the shape).
cd apps/web && npm run lint && npm run typecheck && npm run build
175
+
```
176
+
177
+
Coverage includes the security-critical **workspace isolation** tests, the ingestion pipeline (with a fake vector store + mock embeddings), and the RAG answer path including citation mapping and the not-found guardrail.
110
178
111
-
-**Tenant isolation** is enforced at the SQL layer (workspace-scoped queries + membership checks) **and** the vector layer (every Qdrant search carries a mandatory `workspace_id` filter).
112
-
- Uploaded files are validated by type/MIME and size.
113
-
- Retrieved document chunks are treated as **data, not instructions** (prompt-injection defense).
114
-
- Important actions are recorded in audit logs.
179
+
## Project status & roadmap
115
180
116
-
## Project status
181
+
**MVP complete** — the full loop works: upload → process → ask → cited answer, workspace-isolated.
117
182
118
-
🚧 Under active construction. Current: **Phase 0 — foundation scaffold.** See the phased roadmap in [`docs/TECHNICAL_PLAN.md`](docs/TECHNICAL_PLAN.md).
183
+
-[x]**Phase 0** — Foundation (monorepo, Docker, CI, healthchecks)
0 commit comments