Architecture Guide

Sustainable, governed, extensible architecture and productionisation options.

Ignite Firestarter Architecture Guide

Current as of: 2026-06-19 11:58 +01:00

Purpose

Firestarter is the AI operations hub for Ignite. It provides a governed chat harness, module and agent catalogue, repo-synced skills, repo-synced context, and managed connections to MCP servers and enterprise systems.

The current demo architecture proves the pattern with three agents:

  • Probably Fine: operational health and morning checks through mcp.ignite.systems.
  • Panopticon: SDLC health, Linear/Grafana analysis, poller status, and cross-system delivery intelligence.
  • Handover Hub: project handover drafts from Linear projects and linked GitHub pull request evidence.

Current Runtime Architecture

flowchart TB
  subgraph UserSurfaces[User surfaces]
    Browser[Browser chat UI]
    Docs[Docs page]
    Admin[Admin console]
    Settings[Settings]
  end

  subgraph Firestarter[Firestarter Web - Nuxt/Nitro]
    Auth[Auth boundary\nIgnite Entra primary\nGitHub fallback hidden]
    Chat[Chat orchestrator\nSSE, persistence, copy/export]
    Router[Skill and context router\nbudgets, prefetch, compaction]
    Policy[Security policy\nroles, groups, tool scopes]
    Models[Model gateway\nGitHub Models, Azure OpenAI, OpenAI]
    Hub[MCP hub\ndiscovery, routing, execution]
    Tokens[Encrypted user connector tokens]
    Audit[Audit logging\nrequest IDs, PII scrubbing]
  end

  subgraph Source[Governed source of truth]
    AiTree[ignite/ai\nagents, skills, context]
    Sync[Admin managed sync sources]
  end

  subgraph Tooling[Connector and tool surfaces]
    Wintrix[Wintrix MCP\nProbably Fine]
    Panopticon[Panopticon MCP\nLinear, Grafana, TrackingTime]
    Notion[Notion MCP]
    Graph[Microsoft Graph / 365]
    GitHub[GitHub APIs]
  end

  Browser --> Auth
  Browser --> Chat
  Docs --> Router
  Admin --> Policy
  Admin --> Sync
  Settings --> Tokens
  AiTree --> Sync --> Router
  Chat --> Router --> Policy
  Policy --> Models
  Policy --> Hub
  Tokens --> Hub
  Hub --> Wintrix
  Hub --> Panopticon
  Hub --> Notion
  Hub --> Graph
  Hub --> GitHub
  Models --> Chat
  Hub --> Chat
  Chat --> Audit
  Policy --> Audit

Source Of Truth

The ignite/ai tree is the source of truth for AI context, agents, skills, and security guidance.

  • ai/context: shared organisational and operating context.
  • ai/agents: agent instructions, module catalogue entries, and business context.
  • ai/skills: reusable Codex or Firestarter skills discovered from SKILL.md.
  • ai/skills/probably-fine: Probably Fine MCP and operations material.
  • ai/agents/panopticon: Panopticon instructions, dashboards, and analysis patterns.
  • ai/agents/handover-hub: Handover Hub module instructions, connector rules, and logo assets.
  • ai/skills/handover-hub: the reusable handover drafting skill discovered by Firestarter.

Firestarter syncs from GitHub into a local cache and database. It does not try to become the primary knowledge repository.

Firestarter Web Source Layout

The web app source is grouped by runtime boundary rather than by catch-all utility files:

apps/firestarter-web/
  server/
    api/                 request handlers and route-specific orchestration
    middleware/          request ID and response security headers
    plugins/             runtime startup checks and MCP registration
    utils/
      auth/              session, Entra, bridge auth, GitHub fallback auth
      chat/              prompt assembly, model gateway, context budgets, safety
      connectors/        per-provider token helpers and external API adapters
      mcp/               MCP hub, tool permissions, approvals, write guards
      platform/          Prisma, audit logging, request IDs, readiness, rate limits
      sync/              context, skill source, and identity-map sync helpers
  pages/                 Nuxt pages and primary UI surfaces
  composables/           browser-side auth, markdown, and UI helpers
  docs/                  grouped guide, architecture, security, operations docs

When adding new code, prefer the narrowest matching folder. For example, a new
Linear PAT helper belongs in server/utils/connectors, while a new prompt
budgeting rule belongs in server/utils/chat.

Module And Agent Pattern

New modules should follow the same shape as Panopticon and Handover Hub:

  1. Put durable instructions, source catalogues, permissions, and assets under ai/agents/<agent-slug>.
  2. Put reusable chat playbooks under ai/skills/<skill-slug>/SKILL.md, or under a repo-scanned .agents/skills/<skill-slug>/SKILL.md path.
  3. Expose system access through an MCP server written in TypeScript or C#.
  4. Seed the Firestarter module with a module slug, logo, starter prompts, skill paths, and MCP server slug.
  5. Keep write actions disabled until the tool has explicit confirmation, audit logging, permissions, and rollback/repair guidance.

This lets a standalone PoC move into Firestarter without preserving ad hoc scripts as the runtime. The old PoC can remain as reference material, but the governed source of truth is ignite/ai plus MCP code.

Authentication

Primary sign-in uses Ignite Entra. GitHub OAuth is retained as a hidden admin
fallback for the transition period and should not be treated as the normal user
entry point.

Private GitHub repo access is handled separately by a user supplied GitHub PAT,
stored encrypted server-side and never redisplayed. Server-level
NUXT_GITHUB_TOKEN remains an admin fallback for shared demo environments.

The repo PAT is used first for context sync, skill sync, and
GitHub-authenticated MCP access where a user needs their own entitlements.

Ignite Entra and Verisk Entra remain separate routes: Ignite Entra is for the
Firestarter application identity; Verisk Entra/Graph is for SharePoint, OneDrive,
calendar, mail, and Teams access once delegated scopes are approved. Until then,
SharePoint access is best exposed through approved MCP connectors or manually
curated repo context.

Model Providers

Firestarter supports provider selection behind a common chat interface:

  • GitHub Models for the current demo.
  • Azure OpenAI for managed production hosting.
  • OpenAI or ChatGPT Enterprise style keys for user or service testing.
  • Future Microsoft 365 Copilot connectors once admin approval and tenant setup are available.

User-owned model tokens are encrypted, scoped to that user, and may be overwritten or removed.

MCP And Tooling

MCP servers are registered in runtime config and surfaced as module connections.

The intended pattern is:

  • Firestarter handles user identity, chat state, policy, permissions, and prompt assembly.
  • MCP servers handle specialised domain actions and system integrations.
  • Tool calls carry user context and are permission checked before execution.
  • Destructive or higher risk actions require explicit human approval.

Current MCP servers:

  • wintrix-mcp: operations health, jobs, pods, errors, alerts, Sentry, LaunchDarkly, PostHog, and related operational data as connector setup matures.
  • panopticon-mcp: SDLC and delivery intelligence, Linear snapshots, dashboard readiness, poller health, and analysis context.

Context Budgeting And Chunking

Firestarter uses layered context budgeting because every model has a finite request window and MCP tool schemas can be large.

The current pattern is:

  • Tool pruning: the chat route selects the smallest useful tool set for the current turn, such as Refine Ticket tools, Handover Hub tools, or personal Linear issue tools.
  • Deterministic prefetch: obvious reads such as get_linear_issue, draft_project_handover, and list_my_linear_issues are called before the model response so the model receives concise evidence rather than guessing which tool to call.
  • Conversation compaction: recent turns stay intact, while older turns become a compact summary that preserves issue keys and source URLs.
  • Synced skill budgets: skill instructions are clipped per skill and should reference shared context rather than copy large standards into every skill.
  • Source layout for future retrieval: durable facts belong in ignite/ai/context and ignite/ai/agents, making it straightforward to add embeddings/vector search later.

This keeps small prompts small. For example, hi should not send every MCP schema, and all my Linear issues across teams should route to a per-user Linear assignment tool instead of a blank generic search.

flowchart LR
  User[User message] --> Router[Intent and module router]
  Router --> ToolPrune[Prune MCP tool surface]
  Router --> SkillPick[Select synced skills/context]
  Router --> Prefetch[Deterministic tool prefetch]
  History[Conversation history] --> Compact[Recent turns + older summary]
  ToolPrune --> Prompt[Budgeted prompt assembly]
  SkillPick --> Prompt
  Prefetch --> Prompt
  Compact --> Prompt
  Prompt --> Model[Selected chat model]
  Model --> Guard[Tool permissions and write guards]
  Guard --> MCP[MCP servers]
  MCP --> Evidence[Structured evidence + source links]
  Evidence --> Model

Permissions

The production direction is role and scope based access:

  • Users are created on first successful OAuth login.
  • New Ignite members can be assigned a default read-only role.
  • Admins can promote users or groups to elevated roles.
  • Roles grant module scopes, tool scopes, data scopes, and action scopes.
  • Tool calls are checked against the effective user scope before execution.

Recommended initial roles:

  • Viewer: chat, docs, read-only modules, read-only MCP tools.
  • Operator: Viewer plus approved operational diagnostics.
  • Analyst: Viewer plus Panopticon analysis tools and dashboard backfills.
  • Admin: user, role, server, and connector administration.

Security Guardrails

The current partial protection set should keep moving toward the OWASP LLM Top 10 controls:

  • Input sanitisation and prompt injection detection.
  • Output sanitisation for XSS and accidental data disclosure.
  • Tool-call allowlisting and per-user permission checks.
  • Human approval for destructive actions.
  • Per-user rate limits for chat/model validation, with token budgets and cost monitoring still to mature.
  • Audit logging for prompts, tool calls, connector use, and permission decisions.
  • System prompt protection and context minimisation.
  • Dependency and MCP server allowlisting.

Panopticon Data Architecture

Panopticon uses a poller and snapshot model rather than relying only on current-state API calls.

  • SQLite is used for historical snapshots and backfill data.
  • Pollers gather Linear, TrackingTime, Zendesk-linked, and dashboard metadata.
  • Grafana dashboards are versioned JSON assets.
  • Point-in-time snapshots preserve state history for sprint and project analysis.
  • Team interpretation rules are encoded per team type.

Team modes:

  • Project sprint teams such as T2 and T5: sprint delivery, project scope, cycle health, initiative progress.
  • Customer portal teams such as CP3O: sprint flow plus customer portal delivery concerns.
  • Backlog/service teams such as SUP, HIP, SEC, STELL, TI, DEVOPS: queue health, ageing, throughput, incident or support context, and backlog hygiene.

Productionisation Options

The clean production route is:

  • Move encrypted token storage to a managed key vault or external secrets pattern.
  • Use GitHub App installation tokens for service sync where possible.
  • Keep user PATs only for user-delegated repo access.
  • Deploy pollers as Kubernetes CronJobs with health dashboards and restart controls.
  • Replace demo SQLite storage with managed PostgreSQL where concurrency and retention require it.
  • Add OpenTelemetry traces for chat, sync, MCP calls, and poller runs.
  • Add admin-managed connector setup screens with per-connector diagnostics.
  • Add tenant-approved Entra app registrations for Ignite and Verisk Graph.

Demo Narrative

The demo story is:

  1. Firestarter is a governed AI hub, not a loose chatbot.
  2. Agents are configured from repo-controlled source.
  3. Context and skills sync from Ignite source control.
  4. MCP servers connect the chat to real operational and delivery systems.
  5. Panopticon proves the same harness can support SDLC analytics and executive reporting.
  6. Security and permissions are visible design constraints, not an afterthought.