Kickoff-Africa/kickoff-ai

# KickoffAI Internal AI chat backend for Kickoff Africa — a private, org-only alternative to ChatGPT powered by Ollama. ## Overview KickoffAI gives every Kickoff Africa team member access to Ollama-powered chat within a governed, auditable system. Org members authenticate via magic link, consume AI within a metered time window, and can request extensions from admins. All conversations and usage are tracked and visible to administrators. ## Features - **Magic link auth** — no passwords; login links sent to org email, expire in 15 minutes and are single-use - **JWT sessions** — stateless auth with jti-based revocation on logout - **Metered access** — 1 hour of free AI time per 12-hour rolling window, tracked cumulatively in seconds - **Extension requests** — users request +1, +2, or +3 bonus hours; admins approve or deny - **Smart model routing** — messages auto-classified by a lightweight Ollama model, then routed to the appropriate configured model (simple/moderate/complex/vision) - **Full conversation history** — all messages stored with model used and token count - **Admin panel** — full visibility into users, conversations, usage stats, and extension requests - **Structured logging** — pino with pretty-printing in development, JSON in production - **OpenAPI docs** — interactive Swagger UI served at `/docs` ## Stack | Layer | Technology | |-------|-----------| | Runtime | Node.js + TypeScript | | Framework | Express 5 | | Database | PostgreSQL | | AI | Ollama (self-hosted, via HTTP API) | | Auth | JWT (`jsonwebtoken`) + magic links | | Logging | pino + pino-http | | Docs | swagger-jsdoc + swagger-ui-express | ## Getting Started ### Prerequisites - Node.js 18+ - PostgreSQL 14+ - An Ollama server reachable over HTTP (with the desired models pulled) - SMTP credentials (or `NODE_ENV=development` to log magic links to console) ### Installation ```bash git clone cd kickoff-ai npm install ``` ### Configuration ```bash cp .env.example .env ``` Edit `.env`: …