CitePilot — Documentation Repository

AI-Powered Academic Citation Consistency Checker

This repository contains the complete product, design, engineering, and operational documentation for CitePilot, alongside the working codebases (citepilot-web, citepilot-ai, supabase/migrations).

CitePilot checks in-text citations against reference lists, validates sources against Crossref/DOI.org, detects hallucinated and retracted references, and reports style-rule and structural issues — with PDF and annotated-DOCX exports. It supports 10 citation styles (APA 7, APA 6, Harvard, Vancouver, Chicago Author-Date, Chicago Notes-Bibliography, MLA 9, IEEE, OSCOLA, Turabian).

System at a glance: web on Vercel (Next.js 16.2) · gateway + AI service on Railway (Node 22/Express + Python 3.12/FastAPI) · Vercel Postgres (PostgreSQL 16, Drizzle) · Google Gemini 2.5 Flash as the sole LLM · Crossref validation · PayPal subscriptions. Sessionless, synchronous MVP (see 04-engineering-standards/18-architecture-decision-records.md ADR-008–011).

Note: the working code is vendored in this monorepo (citepilot-web/, citepilot-ai/, supabase/migrations/) — not as git submodules. The citepilot-gateway referenced in older docs is not present as a separate checkout; AI calls go via next.config.ts rewrites to NEXT_PUBLIC_API_URL (Railway). See AGENTS.md and LEARNING.md for navigation rules and deployment quirks.

---

Quick Start Guide

Topic	Doc
System architecture	10-system-architecture.md
Every tech choice with rationale	11-technology-stack.md
API contract (executable)	12-api-specification.md
Database schema (SQL source of truth)	13-database-schema.md
AI/NLP pipeline	14-ai-nlp-design.md
Infrastructure & deployment (Vercel/Railway)	15-infrastructure-deployment.md
Architecture decision records	18-architecture-decision-records.md
Runbooks (deploy/rollback/secrets)	25-runbooks.md
Disaster recovery	27-disaster-recovery.md

---

Documentation Index

01 — Discovery & Strategy

#	Document	Description
01	Competitive Analysis	Reciteworks and the citation-checker market: feature comparison, pricing benchmarks, positioning.
02	Product Requirements Document	Vision, target users, feature set, success metrics, constraints.
03	User Story Map	Epics and user stories with acceptance criteria.
04	GTM Strategy	Go-to-market plan, channels, funnel.
05	Business Model	Pricing tiers, unit economics, cost model.

02 — Design

#	Document	Description
06	Design System	Brand palette, typography, components, accessibility baseline.
07	Information Architecture	Site structure, navigation, route map.
08	Wireframes & Mockups	Page-level layouts and flows.
09	UX Specification	Interaction requirements, states, edge cases.

03 — Technical Architecture

#	Document	Description
10	System Architecture	Component model, data flow, architecture decisions.
11	Technology Stack	Every tech choice with rationale and alternatives.
12	API Specification	The live /api/v1 contract (analyse, exports, health).
13	Database Schema	PostgreSQL design vs the supabase/migrations implementation.
14	AI/NLP Design	Parser → extractor → matcher → style → validation pipeline.
15	Infrastructure & Deployment	Vercel + Railway hosting, environments, scaling, costs.
16	Security Architecture	Threat model, data handling, secrets, upload validation.

04 — Engineering Standards

#	Document	Description
17	Engineering Guidelines	Repo structure, code style, PR process, logging, security standards.
18	Architecture Decision Records	ADR-001–011 including Gemini, Vercel+Railway, PayPal, synchronous MVP.
19	Testing Strategy	Vitest/pytest/Playwright, golden datasets, CI gates, security scans.
20	Monitoring & Observability	Current platform-native state; Datadog/Sentry/status-page roadmap.

05 — Legal & Compliance

#	Document	Description
21	Terms of Service	User-facing ToS.
22	Privacy Policy	GDPR/UK GDPR, 36-hour document retention, data flows.
23	Cookie Policy	Cookies (analytics/consent).
24	Accessibility Statement	WCAG stance and roadmap.

06 — Operations

#	Document	Description
25	Operational Runbooks	Deploy, rollback, migrations, secrets rotation, Gemini/Crossref outages.
26	Incident Response	Severity levels, response checklist, post-mortems.
27	Disaster Recovery	RTO/RPO, backups (Vercel Postgres), platform failure recovery.

07 — Launch

#	Document	Description
28	Launch Checklist	Pre-launch verification across compliance, security, performance, support.
29	Support Documentation & Help Centre	User-facing guides and FAQ.

---

Repository Structure

citepilot-docs/
├── README.md                          ← You are here
├── AGENTS.md                          ← Agent navigation + deployment rules
├── LEARNING.md                        ← Project gotchas & root causes (read first)
├── DESIGN.md
├── 01-discovery-strategy/
│   ├── 01-competitive-analysis.md
│   ├── 02-prd.md
│   ├── 03-user-story-map.md
│   ├── 04-gtm-strategy.md
│   └── 05-business-model.md
├── 02-design/
│   ├── 06-design-system.md
│   ├── 07-information-architecture.md
│   ├── 08-wireframes-mockups.md
│   └── 09-ux-specification.md
├── 03-technical-architecture/
│   ├── 10-system-architecture.md
│   ├── 11-technology-stack.md
│   ├── 12-api-specification.md
│   ├── 13-database-schema.md
│   ├── 14-ai-nlp-design.md
│   ├── 15-infrastructure-deployment.md
│   └── 16-security-architecture.md
├── 04-engineering-standards/
│   ├── 17-engineering-guidelines.md
│   ├── 18-architecture-decision-records.md
│   ├── 19-testing-strategy.md
│   └── 20-monitoring-observability.md
├── 05-legal-compliance/
│   ├── 21-terms-of-service.md
│   ├── 22-privacy-policy.md
│   ├── 23-cookie-policy.md
│   └── 24-accessibility-statement.md
├── 06-operations/
│   ├── 25-runbooks.md
│   ├── 26-incident-response.md
│   └── 27-disaster-recovery.md
├── 07-launch/
│   ├── 28-launch-checklist.md
│   └── 29-support-documentation.md
├── citepilot-web/                     # Next.js 16.2 frontend (vendored)
├── citepilot-ai/                      # Python 3.12 FastAPI AI service (vendored)
├── supabase/
│   └── migrations/                    # SQL schema (14 files) — DB source of truth
└── brand/
    └── guidelines/

---

How to Use This Documentation

• All roles: Competitive Analysis + PRD for strategic context; Launch Checklist for readiness.
• Engineers: System Architecture → Technology Stack → API Spec → Database Schema. Operate with Runbooks and Disaster Recovery. Decisions: ADR Registry.
• Designers: Design System → UX Specification.
• QA/Compliance: Testing Strategy, Monitoring, legal docs in 05-legal-compliance/.

---

Document Conventions

• All docs are Markdown with YAML-style headers (Document ID, Version, Last Updated, Status, Owner).
• Update Last Updated and increment Version on substantive changes.
• Cross-references use relative paths — keep them valid.
• On-disk document IDs use the schemes CP-DS-0XX, CP-ARCH-0XX, CITE-ENG-0XX, CP-OPS-0XX, CP-LAUNCH-0XX (stated in each file's header). Previous README versions claimed a CP-PROD-0XX scheme — that is obsolete.
• When code and docs disagree, executable code wins (API contract: citepilot-ai/src/api/; schema: supabase/migrations/).

---

Contributing

1. Update the document header (Last Updated, Version).
2. Keep all cross-references valid.
3. Update this README when adding documents or changing structure.
4. Substantive technical changes should cite or create an ADR (04-engineering-standards/18-architecture-decision-records.md).

---

Last updated: 11 August 2026