Mashirika Law — PBO Act platform

Production deploy: The live app must build from the repository root, not prototype/web.
If https://creco-kenya.vercel.app still shows old home stats or a dark AI-style footer, follow DEPLOY.md.

Live on Vercel

1. Push this repo to GitHub (kendagordavid/creco_kenya).
2. In Vercel, Import the repository.
3. Use default settings — Framework: Next.js, Root Directory: (empty / repo root).
4. Add environment variables:
   • AUTH_SECRET — session signing secret (required for login)
   • POSTGRES_URL — from Storage → Neon (required for users, submissions, feedback)
   • GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET — optional, enables Google sign-in on /login
   • OPENAI_API_KEY — optional, for AI-polished guidance answers (Production + Preview)
5. After first deploy, run npm run db:setup locally with the Neon POSTGRES_URL to create tables and seed demo users.
6. Deploy.

URLs after deploy:

URL	What
/	Platform home — all five modules
/knowledge	Knowledge hub (topics, FAQs, toolkits, media)
/compliance	Checklist, self-assessment, templates
/guidance	PBO Act guidance Q&A
/monitoring	Civic space monitoring reports
/login	Sign in (demo: [email protected] / demo1234)
/register	PBO user registration
/search	Global search
/sources	Source documents
/topics	Topic library (legacy route)

Set AUTH_SECRET in Vercel (Production + Preview) — generate with openssl rand -base64 32.

Google sign-in (optional)

1. In Google Cloud Console, create an OAuth 2.0 Client ID (Web application).
2. Add Authorized redirect URIs:
   • Local: http://localhost:3000/api/auth/callback/google
   • Production: https://your-domain.example/api/auth/callback/google
3. Copy the Client ID and Client Secret into .env.local (local) and Vercel env vars (Production + Preview):

   GOOGLE_CLIENT_ID=...
   GOOGLE_CLIENT_SECRET=...
   

4. Restart the dev server or redeploy. The login page shows Sign in with Google when both vars are set.

Check http://localhost:3000/health for a readable status page (or /api/health for raw JSON). Google sign-in should show as configured.

The site includes built-in API routes (/api/ask, /api/sources, …) that read wiki topics from prototype/wiki/. You do not need a separate backend for demos.

Optional: set NEXT_PUBLIC_API_URL to a deployed FastAPI server instead.

CLI deploy:

npx vercel          # preview
npx vercel --prod   # production

Local development

npm install
cp .env.local.example .env.local   # set AUTH_SECRET and POSTGRES_URL
npm run db:setup                     # create tables + seed demo users
npm run documents:sync               # copy approved PBO PDFs into public/documents
npm run dev

Place the approved source PDFs at the repo root before running documents:sync:

• PBO ACT 2013.pdf
• Kenya Gazette Supplement No. 67 Legal Notice No. 43 - PBO Regulations.pdf

They are copied to public/documents/ as pbo-act-2013.pdf and pbo-regulations-2026.pdf.

Additional source PDFs: place the file in public/documents/. It will appear on /sources automatically. For a custom title or type, copy data/source-documents.example.json to data/source-documents.json and add an entry (same filename as on disk).

Local Postgres: create a database, then point POSTGRES_URL at it:

sudo -u postgres createdb creco_pbo
# POSTGRES_URL=postgresql://postgres:YOUR_PASSWORD@localhost:5432/creco_pbo

Same Neon DB as Vercel: copy POSTGRES_URL from Vercel → your project → Storage → Neon into .env.local. Local dev and production then share one database.

Open http://localhost:3000.

Python backend (optional):

cd prototype/backend && source .venv/bin/activate
uvicorn app.main:app --reload --port 8000
# Then set NEXT_PUBLIC_API_URL=http://localhost:8000 in .env.local

Inception report (ToR Deliverable #1)

Full project inception report — methodology, architecture, and 32-week work plan (inception through post-deployment support):

Format	Location
Markdown (source)	docs/Inception-Report-CRECO-PBO-Platform.md
HTML (CRECO review)	docs/inception-report.html

Open the HTML version in a browser and use Print → Save as PDF for submission.

Repo layout

Path	Purpose
app/, components/, lib/	Next.js frontend + Vercel API
docs/	Sitemap, user journeys, full inception report
prototype/wiki/	PBO Act topic pages (bundled with deploy)
prototype/backend/	Optional FastAPI server

See prototype/HOW_TO_USE.md and prototype/DEPLOY_VERCEL.md.