Architecture — Developer Reference

This reference enables developers and AI agents to understand and work on the project. Treat it as the source of truth for architecture and file locations.

Project Identity

Field	Value
Name	RFS Hub (RedFlag Security Hub)
Company	RedFlag Security (one word, never "Red Flag")
Location	Ottawa, Ontario, Canada
Business	Alarm systems, CCTV cameras, access control, intercom systems
Package name	`rfs-hub`
Repo	georgesfahd/redflag-chatbot (GitHub)
Node requirement	≥ 18
Hosting	Vercel (Hobby plan — no cron jobs)

Tech Stack

Layer	Technology	Version
Framework	Next.js (App Router)	16.1.6
UI	React	19
Language	TypeScript	5.7
Database	Supabase (PostgreSQL + Auth + SSR)	@supabase/supabase-js 2.47
AI	Google Gemini	@google/generative-ai 0.21
Styling	Tailwind CSS 4 + CVA	4.0
UI Components	Radix UI (shadcn-style) + cmdk	Multiple
Icons	lucide-react	0.460
Linting	ESLint 9 + eslint-config-next	9.16

Getting Started

npm install
cp .env.example .env.local   # Fill in all required keys
npm run dev                   # http://localhost:3000 (Turbopack)

Scripts: dev (Turbopack), build, start, lint, db:schema-dump.

Directory Structure

src/
├── app/           # Next.js App Router (admin, api, portal, tech, estimate, etc.)
├── components/    # admin, chat, estimate, tech, ui (Radix/shadcn)
├── lib/           # estimate/, email-monitor/, qbo/, supabase/, config, gemini, gmail, rate-limit
├── types/         # database.ts (TABLES, BOTS), estimate.ts
├── hooks/
└── proxy.ts  # Auth (edge)

Key Patterns

Database: Always use TABLES.xxx and BOTS.xxx from src/types/database.ts. Use createServiceClient() for server-side DB; createServerClient() for auth checks.
API: Rate limiting on public endpoints via rateLimitCheck(). Admin APIs check Supabase session. Streaming uses text/plain and X-* headers.
AI: Tags in HTML comments: ANSWER, CHIPS, QTY_SELECTOR, etc. Default model: gemini-2.0-flash. Integration in src/lib/gemini.ts.
Business: HST 13%; estimate numbers EST-XXXXXXXX; ticket refs TKT-XXXXXX.
UI: shadcn-style Radix primitives in src/components/ui/; icons from lucide-react only.