`README.md`

126 lines
# Norma

Multi-tenant nonprofit intelligence platform. Three-tier UI: **Norma** (admin), **Nikki** (org staff), **Pulse** (end user). Covers email & outreach, Gmail CRM, news intelligence, petition management, and a credential platform for issuing & managing API access.

---

## Quick Start

```bash
# Install deps
npm install

# Run migrations
psql "$DATABASE_URL" -f db/schema.sql
for f in db/migrations/*.sql; do psql "$DATABASE_URL" -f "$f"; done

# Dev server (port 7400)
npm run dev
```

Default login: `admin` / `DWSecure2024!`

---

## Stack

- **Framework:** Next.js 16 (App Router) + React 19
- **Styling:** Tailwind 4, CSS variables, dark-theme only
- **Database:** PostgreSQL 16 (`sdcc` database)
- **Auth:** Cookie-based with bcrypt password hashing, role-based routing
- **AI:** Gemini 2.0 Flash for enrichment, chat, analysis
- **Icons:** `lucide-react` (exclusive — no other icon packages)

---

## Documentation

| Doc | Audience |
|-----|----------|
| [`docs/credential-system.md`](docs/credential-system.md) | Admins operating the credential platform |
| [`docs/api/v1.md`](docs/api/v1.md) | External consumers integrating against `/api/v1/*` |
| [`docs/api/openapi.yaml`](docs/api/openapi.yaml) | Machine-readable API spec for SDK generation |
| [`docs/security-audit-2026-04.md`](docs/security-audit-2026-04.md) | Security audit report |
| [`docs/wcag-audit-2026-02-23.md`](docs/wcag-audit-2026-02-23.md) | Accessibility audit |
| [`docs/sessions/`](docs/sessions/) | Session logs, learnings, task tracking |
| [`docs/plans/`](docs/plans/) | Planning documents |
| [`docs/superpowers/`](docs/superpowers/) | Feature specs and implementation plans |
| [`CLAUDE.md`](CLAUDE.md) | AI assistant guide — design tokens, component classes, conventions |

---

## Key Modules

| Area | Entry point |
|------|-------------|
| Auth | `lib/auth.ts`, `lib/require-role.ts` |
| Database | `lib/db.ts` (pg Pool) |
| Audit logging | `lib/audit.ts` |
| Credentials (API keys + social) | `lib/credentials.ts`, `lib/api-key-auth.ts` |
| Gmail OAuth | `lib/gmail.ts` |
| AI (Gemini) | `lib/chat.ts`, `lib/ingest-news.ts` |
| Brand config | `lib/brand.ts` |

---

## Agents

Norma ships with autonomous agents in `agents/`:

- `twitter-agent`, `bluesky-agent`, `facebook-agent`, `instagram-agent` — social posting & monitoring
- `price-agent` — price tracking
- `shared/credentials.js` — DB-first credential loader used by all agents

Each agent loads credentials via `loadCredentials(platform)` with env-var fallback and a 5-min TTL cache.

---

## Development Conventions

- **All components are `'use client'`** (client-side rendering)
- **Never hardcode colors** — use CSS variables from `app/globals.css`
- **Reuse pre-defined classes** (`.card`, `.btn-primary`, `.badge-success`, `.input`) — don't recreate them
- **Icons from `lucide-react` only**
- **All URLs in docs/examples use `http://45.61.58.125:7400`** — never `localhost`

See [`CLAUDE.md`](CLAUDE.md) for the full design system spec.

---

## Session Tracking

Every session logs to `docs/sessions/`:

- `sessions.md` — session summaries
- `tasks-requested.md` — every user request
- `tasks-completed.md` — completed work with files
- `learnings.md` — technical learnings

---

## Backup

Nightly git bundle → Google Drive:

- Script: `/root/backups/norma-backup.sh`
- Cron: `0 10 * * *` UTC (2 AM PT)
- Retention: 7 days local, 30 bundles on `gdrive:Projects-Backup/Norma/`

---

## Security

- Bcrypt password hashing (transparent migration from legacy SHA-256)
- Role-based API gating via `requireRole()` / `verifyCronAuth()`
- Edge Runtime middleware validates token structure + expiry
- Audit log entries for key operations (`auditLog(action, resource, id, meta)`)
- API keys: bcrypt-hashed with prefix index (GitHub PAT pattern)

Full audit: [`docs/security-audit-2026-04.md`](docs/security-audit-2026-04.md)

---

## License

Proprietary.