Skip to Content
AssistantOverview

Overview

The assistant/ folder is an internal AI chatbot for the IBA staff team. One conversational interface that can answer questions across the services we run day-to-day — codebase, project docs, MySQL data — and (as of Phase 4) external services like Sentry, GitHub, Jira.

The medium-term intent is to replace three previously separate tools (the abandoned personal dashboard, tunnelflight-health-monitor, tunnelflight-log-analyzer) with one assistant that does all of it, plus answers ad-hoc questions in chat.

What it can do today

  • Answer business-data questions backed by curated MySQL queries (members, payments, currency, channel logbook). The LLM picks the right tool from ~20 predefined queries rather than running arbitrary SQL.
  • Surface docs content with full-text search and read-by-path tools.
  • Search and read code across the monorepo.

Live deployment

  • URL: assistant.tunnelflight.com  (DO default ingress for debugging: tunnelflight-assistant-324lw.ondigitalocean.app)
  • Access: IBA staff only (admin role + role_id=10). Logs in via the standard IBA credentials with TOTP, proxied through api/.
  • Stack: Next.js 15 + React 19 (App Router for UI, Pages Router for the /api/auth/* proxy)
  • Hosting: DigitalOcean App Platform component tunnelflight-assistant
  • Database: shares the prod MySQL cluster with api//www//admin/. Assistant-owned tables live in their own tunnelflight_assistant schema; curated tools read from the main IBA schema via a read-only user

Architecture

Technology stack

  • Framework: Next.js 15 (React 19, App Router for UI, Pages Router for auth-proxy routes)
  • LLM: Anthropic Claude (claude-sonnet-4-6 by default; tunable via ASSISTANT_MODEL)
  • Database: MySQL 8 via mysql2. Two pools: one for assistant-owned writes (tunnelflight_assistant schema), one read-only for curated tool reads (main IBA schema).
  • Auth: cookie-based JWT minted after proxy-login to api/. Role allowlist enforced both at the proxy entry and in middleware.
  • Logging: Winston structured JSON + Sentry error tracking (component tag assistant)
  • Design system: @tunnelflight/design-system (workspace package) — Radix-based shadcn primitives + IBA composites.

Connectors and tools

The agent loop is driven by Anthropic’s tool use. Tools are registered by connectors at boot. Today’s connector set:

ConnectorTool countReads from
docs3 (list/read/search)docs/app/**/page.mdx
code3 (list/read/search)Monorepo source tree
mysql20 (curated queries)Main IBA schema via read-only assistant_app user

Phase 4 adds MCP-sidecar connectors for Sentry, GitHub, Jira.

Project structure

assistant/
├── src/
│   ├── app/                   # App Router (UI: /chat, /login)
│   ├── pages/api/auth/        # Pages Router (login/logout proxies)
│   ├── components/chat/       # Sidebar, ChatPanel, Composer, UserMenu
│   ├── infrastructure/
│   │   ├── connectors/        # docs / code / mysql tool definitions
│   │   ├── persistence/       # MysqlUserRepository, conversation repo
│   │   └── lifecycle.ts       # Connector init order, healthcheck wiring
│   ├── domain/                # User, conversation, message types
│   ├── lib/                   # logger, sentry, infisical bootstrap
│   ├── hooks/                 # useAssistantChat
│   ├── middleware.ts          # Cookie auth + role allowlist
│   ├── instrumentation.ts     # Next.js boot hook (runtime split)
│   └── instrumentation-node.ts # Node-side init (Sentry, lifecycle)
├── sql/migrations/            # 0001-0007 (assistant schema + grants)
├── scripts/                   # dev-up.sh, env-pull.sh, migrate.ts
├── specs/                     # Phase-by-phase spec docs (01..07)
├── docs/PLAN.md               # Authoritative implementation plan
├── docs/CONVENTIONS.md        # Coding rules (Result pattern, layering)
└── package.json

Getting started

Prerequisites

  • Node 20.11.1
  • Docker (for local MySQL + Redis via monorepo docker compose)
  • Infisical CLI (brew install infisical/get-cli/infisical)
  • Local api/ running on :8080 (the assistant proxies /api/auth/* through it)

Local dev

cd assistant
cp infisical.env.example infisical.env  # paste machine-identity creds
npm install
npm run dev:up                            # pulls secrets, syncs MySQL user, runs migrations, starts next dev

Open localhost:3001  and log in with your IBA credentials.

  • Deployment — Infisical↔DO sync, env vars, token rotation, redeploy
  • assistant/docs/PLAN.md (in-repo) — the long-form implementation plan with phase-by-phase build sequence
  • assistant/docs/CONVENTIONS.md (in-repo) — Result pattern, layering, where SQL lives
  • assistant/specs/<phase>/ (in-repo) — per-phase spec + plan + tasks
Last updated on
Overview