`CLAUDE.md`

71 lines
# Freddy - The Fundraising Coordinator

## Project Info
- **Directory**: /root/Projects/Freddy/
- **Port**: 7470 | **PM2**: freddy-app
- **Database**: connection string lives in `.env.local` (DATABASE_URL); use `dw_admin@127.0.0.1:5432/freddy`. NEVER commit credentials to docs.
- **Auth**: admin / (AUTH_PASSWORD env — see .env.local; no longer hardcoded)
- **Stack**: Next.js 15 (App Router) + Tailwind 4 + PostgreSQL + Gemini AI
- **URL**: http://45.61.58.125:7470

## Purpose
Democratic funding marketplace that flips traditional grant funding from top-down to bottom-up.
Citizens vote on causes, non-profits register capabilities, granters see ranked leaderboards,
AI matches cause urgency + non-profit capability + granter preferences into a funding pipeline.

## Revenue Model
- **Introduction Fee**: $750 flat (paid by requesting party)
- **Success Fee**: 5% of grant amount (paid by non-profit from grant funds, only if awarded)
- **No upfront costs for granters**
- **NOT A FIDUCIARY**: Freddy never touches grant money, introduction and facilitation only.

## Key Concepts
- **Causes**: Issues citizens care about, ranked by votes and urgency
- **Organizations**: Non-profits addressing causes, scored by trust and impact
- **Granters**: Funding organizations with budgets and focus areas
- **Matches**: AI-generated cause-to-org-to-granter pipeline recommendations
- **Solicitor**: Contact harvesting + AI-generated outreach letters for both parties
- **Revenue**: Fee tracking for introduction fees and success percentages
- **Impact Reports**: Outcomes tracking after funding is distributed

## Database Tables
users, organizations, granters, causes, votes, matches, funding_rounds, impact_reports, audit_events, revenue, contacts

## Sidebar Tabs
1. Pulse Board (BarChart3) - Main dashboard with stats, pipeline, trending causes, top orgs
2. Causes (Flame) - Browse/vote/discover causes
3. Organizations (Building2) - Non-profit registry
4. Granters (Landmark) - Funding organizations
5. Matches (Sparkles) - AI cause-to-org-to-granter matches
6. Solicitor (Send) - Contact harvesting + outreach letter generation
7. Revenue (DollarSign) - Fee tracking and commissions
8. Impact (TrendingUp) - Outcome reports
9. Settings (Settings) - Platform configuration

## API Routes
- Auth: /api/auth/login, /api/auth/logout, /api/auth/session
- CRUD: /api/causes, /api/organizations, /api/granters, /api/matches, /api/votes, /api/funding, /api/impact, /api/contacts, /api/revenue
- AI: /api/causes/discover, /api/matches/generate, /api/contacts/discover, /api/contacts/generate-letter
- Dashboard: /api/pulse

## Theme
Amber/Gold dark theme: primary #d97706, accent #fbbf24
Background: #0f0d0a, Surface: #171310, Surface-el: #1f1b16
Border: #2d2820, Text: #f5f0e8, Muted: #8a8070

## Key Files
- lib/db.ts - Postgres pool
- lib/auth.ts - Cookie auth (freddy-auth cookie, SHA-256 HMAC, 24h expiry)
- lib/audit.ts - Audit logger
- components/AppShell.tsx - Main app shell with sidebar routing
- components/Sidebar.tsx - 9-tab sidebar with amber active indicator
- components/pulse/PulseBoard.tsx - Hero dashboard
- components/causes/CausesTab.tsx - Causes with AI discover
- components/organizations/OrgsTab.tsx - Non-profit registry
- components/granters/GrantersTab.tsx - Granter cards
- components/matches/MatchesTab.tsx - AI match pipeline
- components/solicitor/SolicitorTab.tsx - Contact harvesting and letter gen
- components/revenue/RevenueTab.tsx - Revenue tracking
- components/impact/ImpactTab.tsx - Impact reports
- components/settings/SettingsTab.tsx - Platform settings