User Guide

A page-by-page walkthrough of the whole app, written so you can hand it to someone who's never run a sprint in their life and have them figure out which screen to open.

What this app actually is

AIgileCoach reads your Jira board and gives you an opinion. It pulls your tickets, sprints, and dependency links, then surfaces:

• what you should worry about today — blocked work, stale tickets, missing info
• what your team should commit to this sprint — ranked backlog, readiness scores
• where you're losing time — flow metrics, bottlenecks
• and lets an AI model — OpenAI, Anthropic, Mistral, or a local Ollama — write coaching notes, demo scripts, or refactor proposals on top of all of that.

It's a coach, not a replacement for Jira. Jira is still the source of truth; this app is the lens.

If you've never done Agile before — start here

These are the only terms you need to read the rest of this guide:

• Ticket (a.k.a. Issue) — one unit of work in Jira. Has a key like ENG-123, a summary, a status, an assignee.
• The hierarchy — tickets nest. Big things contain smaller things:
  • Epic — a large initiative ("Add SSO support"). Spans weeks/months.
  • Story — a user-visible chunk of an Epic ("As a user, I can sign in with Google"). A few days of work.
  • Task / Sub-task — concrete engineering steps inside a Story. Hours to a couple days.
• Backlog — every ticket that isn't done yet and isn't in the current sprint. Always sorted; the top is what you'll pick up next.
• Sprint — a 1- or 2-week box of work the team commits to finishing. At the end the work is either Done or rolls back to the backlog.
• Ceremonies — the recurring meetings:
  • Standup (daily, 15 min): what did I do yesterday, what am I doing today, what's blocking me?
  • Sprint Planning (start of sprint): pick which backlog items go in.
  • Sprint Review / Demo (end of sprint): show stakeholders what shipped.
  • Retrospective (end of sprint): what went well, what didn't, what we'll change.
• Definition of Ready (DoR) — checklist a ticket must pass before entering a sprint (summary, estimate, acceptance criteria…).
• Definition of Done (DoD) — checklist a ticket must pass before it can be marked done (code merged, tests, docs…).
• Velocity — story points a team completes per sprint. Used to forecast.
• Burndown — how much work is left in the sprint, plotted over time. Should slope down to zero.

Common roles:

• Product Owner (PO) — owns the backlog, decides what to build next.
• Scrum Master (SM) — runs the ceremonies, unblocks the team.
• Developer / IC — does the work.
• Stakeholder — funds it, wants demos.

When this guide says "use this page if you're a SM", swap in whoever holds those responsibilities on your team — the labels don't matter, the activities do.

Setup & admin

/setup — First-run wizard

Use it once, when you install the app or move to a new Jira tenant. Walks you through: Jira URL + credentials, default JQL, optional AI provider key. Come back here only if you wipe your config and want to re-onboard rather than edit YAML by hand.

/settings — Configuration

The big one. Everything tunable lives here as an accordion: default JQL, missing-info audit criteria (presets: minimal/default/strict), prompt-control caps for AI calls, WIP limits per status, story-point limits, Jira servers, teams, AI provider (OpenAI / Anthropic / Mistral / Ollama), config import/export.

Example: your team starts oversizing tickets. Open Settings → Story-point limits → drop max from 13 to 8. Tickets above 8 immediately get flagged on the dashboard and in DoR.

/admin — Workspace admin (SaaS only)

Workspace-level overview: tenant health, member list, system alerts, multi-tenant metrics. Use it when you manage AIgileCoach for a team or org and need a single view of the workspace state.

/projects — Project switcher (SaaS only)

Pick which Jira project / tenant the rest of the app applies to. If your workspace covers multiple projects, this is where you toggle between them. Lite installs are single-project; you won't see this page there.

/team — Team management (SaaS only)

Invite members, assign roles, map Jira groups to app roles, manage permissions. The Enterprise Lite SKU relies on SSO claims instead and doesn't expose this UI.

/billing — Subscription & plan (SaaS only)

Stripe-hosted portal for plan, seats, invoices, payment methods. Free / Team ($29/mo) / Enterprise ($149/mo). Enterprise Lite is perpetual-licensed and skips this page entirely.

/audit / /settings/audit — Audit log

Every config change, every API call, every SSO sign-in is logged. Browse by month, filter by actor or action. Use it when something looks wrong ("who changed the AI provider key last Tuesday?") or for compliance reviews.

/health — System health

Live status of every integration: API up, Jira reachable, AI provider responding, license valid, config readable. Auto-refreshes every 30 seconds; green / amber / red badge at the top. Use it when a page shows weird data — /health tells you whether Jira itself is degraded before you go hunting in logs.

/account — You

Your profile (email, role, SSO method, last sign-in) plus license status card (plan, expiry, days remaining, features included). Use it to verify "yes I'm signed in as the right person" and to check license expiry before the renewal date.

/login — Sign in

Picks the SSO provider configured (SAML, OIDC, or evaluation mode). SaaS additionally has /register, /forgot-password, /reset-password, /verify-email for self-service auth — Enterprise Lite is SSO-only.

Your dashboard

/ — Dashboard

The landing page. Paste a JQL query at the top and you get:

• Epic cards — every Epic matching the query, with title, status, and a progress bar (children completed / total).
• Issue rows — flat list of every matching ticket: key, summary, status, priority, assignee, due date.
• Stats bar — totals and quick warnings (X tickets blocked, Y stale).
• AI Coach panel on the right — context-aware prompts ("summarise this board", "what are the biggest risks?") tied to the current filter.

When to use it: every time you open the app. It's the "what shape is my project in right now?" view.

Example: Monday morning. Paste project = ENG AND sprint in openSprints(). You see one Epic is 80% done, two Stories are blocked, one ticket is 12 days old without an update. Click into the blocked Stories to see why.

Sprint operations

/standup — Daily standup

Built for the 15-minute morning meeting. Top bar = time-window selector (24h / 48h / 72h). Below that, per-person tabs plus an "All" tab. For each person: summary cards (updated / created / resolved / commented / blocked / stale / due-soon counts), accordion sections (Stale items, Approaching due dates, Recently updated, Blocked items, Resolved, Newly created), team workload sidebar.

When to use it: every weekday morning, 5 minutes before standup.

Example: someone is silent in the meeting. Switch to their tab — you can see they updated nothing for 48 hours and have two tickets blocked. Ask about those instead of "what did you do yesterday?".

/planning — Sprint planning

Two tabs: Task list (sortable table of every candidate ticket — inline-edit status / priority / due date) and Calendar (month/week grid with tickets at their due dates, drag to reschedule). Use the table for "how big is the work?"; the calendar for "when do things need to ship?".

/sprint-goals — Sprint goals

A sprint is just a bunch of tickets unless you've stated why. This page is for the 1–3 sentence goal of the sprint ("Ship SSO. Land the analytics rewrite. Reduce signup drop-off by 20%."). For each goal you see progress ring, status (On Track / At Risk / Off Track), linked tickets. Write them on day 1, glance at status mid-sprint, review at retro.

/sprint-review — End-of-sprint demo prep

Header shows the sprint's completion ring and dates. Epic cards roll up story-points done / total. Below: a demo-readiness checklist and an AI panel that drafts talking points from the completed work. Use it the day before sprint review — walk through the checklist, mark things ready, copy the AI-generated demo script into your slides.

/retro — Retrospective

Sprint retrospective board. Categorise notes ("Went well", "Didn't go well", "Try next time"), upvote, AI summarisation distils freeform notes into a short action list. One person drives the screen during the meeting; everyone calls out notes; AI helps reduce them to 2–3 concrete actions before the next sprint.

Role-specific morning views (SaaS only)

SaaS gives each role a tailored dashboard so the first page they open is already filtered for them:

• /sm — Scrum Master view. Blocked tickets, missed standups, capacity overflow.
• /po — Product Owner view. Backlog readiness, upcoming sprint candidates, stakeholder asks.
• /exec — Executive view. Roll-ups across projects, risks, on-track / at-risk badges.
• /me — Personal view. Just your assigned tickets, your blockers, your due dates.

Enterprise Lite gives everyone the same / dashboard and lets the JQL bar do the filtering.

Backlog & structure

/backlog-refinement — Backlog Coach

Scores every ticket in the backlog on readiness: summary present? description? acceptance criteria? estimate? assignee? due date? Oversized? Stale? Missing a parent Epic? Output: urgency score 1–10, sortable table, "X tickets need refinement". Use it in the weekly refinement meeting — sort by score descending, work down the list.

Example: your team has 60 tickets in the backlog. The Coach flags 12 as urgent (no estimate + no AC). You spend the hour fixing those 12 instead of grooming all 60 superficially.

/dor — Definition of Ready

Similar to Backlog Coach but stricter, and aimed at "is this ready to enter the next sprint?". Shows the percentage of items that are Ready / Almost Ready / Not Ready with the missing-criteria chart. Use it the day before sprint planning to argue "no, these three can't enter the sprint until we get acceptance criteria".

/hierarchy — Hierarchy tree

Collapsible tree of the current Epic → Story → Task structure. Status colour-coded, progress bar per parent, urgency flags from the coach. Use it when onboarding a new team member ("here's how our work is shaped") or before sprint planning to spot orphan Stories.

/architecture — AI refactor proposal

AI-driven proposal for restructuring the backlog: tickets to split, merge, rename, re-parent, plus an audit of missing info and a suggested action plan. Use it for the quarterly tidy-up — the AI looks for oversized epics, ticket-naming inconsistencies, and tickets that probably belong elsewhere.

/gantt — Gantt chart

Classic timeline view. Rows = Epics + their child issues, bars span start-to-due, arrows show dependencies, a red vertical line marks today. Use it in release planning when you want to know "if we slip this Epic by two weeks, what else slides?". The arrows make it visible.

Risk, quality & governance

/compliance — Project Health

Scores each Jira project against a set of governance checks (workflow correctly configured, required fields enforced, permissions sane). Each check shows pass/fail with a remediation guide (the ComplianceStepper: click to walk through the fix). Use it when a stakeholder asks "how mature is this team's process?" or after an incident review.

/prioritize — Prioritization

Backlog sorted by a scoring algorithm: explicit priority + due-date proximity + how many other tickets it unblocks − penalty for being blocked. Flags incoherence (circular blockers, stale blockers, orphan urgents, "quick wins"). Use it before sprint planning — the top of the list is your "we're definitely doing this" set.

/dependencies — Dependency graph

Visual blocking chains and cross-project links. Click a node to drill in. Has an "AI Discovery" mode that asks an LLM to find implicit dependencies (shared resources, sequential risks) Jira's link types don't capture. Use it when a sprint is going off the rails to find the one root blocker that's holding up four other tickets.

/roam — Risks

A kanban board for risks (not tickets). Four columns: Resolved / Owned / Accepted / Mitigated. Each card has severity, owner, description, and optionally a linked Jira issue. Use it in the weekly risk review — move cards left as risks get worse, right as they get handled. Anything sitting in Owned for too long is a problem.

/raci — Responsibility matrix

Activities (rows) × people / teams (columns). Each cell is one of R Responsible / A Accountable / C Consulted / I Informed. A validator flags rule violations (every activity needs exactly one A; too many R's = unclear ownership). Use it in quarterly org planning, or when a project keeps drifting because "everyone thought someone else owned it".

/flow — Flow metrics

The Kanban / lean view. Tabs: Burndown (work-left vs. ideal), Velocity (points/sprint, last 8–12), CFD (cumulative flow: where work piles up), Cycle time (size vs. time-to-close scatter with P50 / P85 / P95), Overview (composite alerts). Use it when the team is delivering but you can't tell how well.

/pi-planning, /pi-compliance, /pi-board — SAFe Program Increment (SaaS only)

Multi-team PI Planning for SAFe-style scaled Agile: cross-team objective tracking, dependency board, compliance scoring. Enterprise Lite supports Scrum/Kanban only — these pages are not present there.

/impediments — Blocker register (SaaS only)

Dedicated page for systemic blockers that aren't easily fixed at the ticket level. Lite surfaces blocked tickets inline on the dashboard and standup view rather than as a separate page.

People & learning

/health-check — Team health check

Spotify-style "squad health check". Past voting rounds list + per-session detail screen with 8 categories (Mood, Velocity, Quality, Delivery, Collaboration, Learning, Support, Health). Each person votes 1–5; the page shows distribution + average + freeform comments. Run every 2–4 sprints as part of a retro — trending scores reveal slow-motion problems retros miss.

/expertise — Expertise map

Who knows what, and where the bus factor is dangerous. Tabs: By domain (ranked list of who's most active in each area), By person (each teammate's top contributions and bus-factor risk), Bus factor (percentage of projects with only one effective SME). Use it for vacation rosters, shadowing decisions, or making the case for cross-training.

Analysis

/analytics — Analytics dashboard

Aggregate metrics: velocity trend, sprint completion %, bottlenecks, quality scores, aging WIP, cycle time, team workload, stale tickets, Definition-of-Done compliance. Use it at the start of any meeting where someone says "how's the team doing?" — point at the relevant chart, move on.

/analyze — Deep AI analysis

For when you want the AI to look at the whole board, not just one ticket. Three-step flow: (1) Copy a structured prompt the app generates from your JQL + ticket context; (2) Run it externally (ChatGPT, Claude, etc.) or via the configured provider, then paste the response back; (3) View the parsed sections — risks, recommendations, missing-info audit, action items. Use it for monthly health reviews, or after a stakeholder complaint ("why are we always late?"). The AI is good at spotting patterns across 50+ tickets that humans miss.

Drill-down details

/epic/[key] — Epic detail

Click any Epic anywhere in the app and you land here. Header shows title, status, rolled-up story points, assignee, due date. Below: all child issues in a table, linked Epics, dependencies, AI panel, activity feed. Sprint planning often pivots through here.

/issue/[key] — Issue detail

Same as Epic view but for a single Story / Task / Sub-task. Edit fields, change status, comment, link to other issues, see full change history. This is the page you'll spend the most time on across all of them.

Where each page lives in the sidebar

Sidebar group	Pages
Overview	Dashboard, Analytics
Board Hygiene	Project Health, Definition of Ready, Backlog Coach, Hierarchy
Sprint	Sprint Planning, Prioritization, Sprint Goals, Daily Standup, Flow Metrics, Sprint Review, Retrospective
Backlog	Gantt Chart, Dependencies
PI Planning (SaaS)	PI Board, ROAM Board
Team	Team Health Check, RACI Matrix, Expertise Map
AI Tools	Deep Analysis, Architecture (Refactor)
Admin	Settings, Billing (SaaS), Health, Audit Log

Glossary

Term	Meaning
Epic / Story / Task	Levels of the work hierarchy in Jira (largest to smallest).
Sprint	A 1–2 week box of committed work.
Backlog	Work not yet in a sprint. Always prioritised.
JQL	Jira Query Language — project = ENG AND status = "In Progress". The filter bar takes raw JQL.
DoR / DoD	Definition of Ready (before sprint entry) / Definition of Done (before close).
Velocity	Story points a team completes per sprint, averaged.
Burndown / CFD	Charts of "work remaining" / "work in each status over time".
WIP	Work In Progress — anything started but not done.
PO / SM / IC	Product Owner / Scrum Master / Individual Contributor (a.k.a. developer).
ROAM	Risks: Resolved / Owned / Accepted / Mitigated.
RACI	Responsible / Accountable / Consulted / Informed.
Bus factor	"How many people would have to get hit by a bus before this knowledge is gone?" Lower = riskier.
SAFe / PI	Scaled Agile Framework / Program Increment (multi-team planning cadence).
AI provider	OpenAI / Anthropic / Mistral / Ollama (local). Configured in Settings.

Setup & Configuration

Get AIgileCoach running in minutes.

SaaS (hosted)

1. Register at app.aigilecoach.io/register
2. Follow the setup wizard to connect your Jira server
3. Start using the dashboard

Environment variables

Variable	Default	Description
API_PORT	3011	API server port
FRONTEND_PORT	3010	Frontend port
JIRA_BASE_URL		Jira server URL (alternative to setup wizard)
JIRA_USERNAME		Jira email/username
JIRA_API_TOKEN		Jira API token
MAX_ISSUES_PER_QUERY	500	Max issues fetched per JQL query

Jira Connection

Connect AIgileCoach to your Jira Cloud or Server instance.

Jira Cloud

1. Go to Settings in AIgileCoach
2. Enter your Jira Cloud URL: https://yourcompany.atlassian.net
3. Enter your Atlassian email address
4. Generate an API token at id.atlassian.com
5. Click Test Connection — you should see your projects listed
6. Select the projects you want to track and save

Jira Server / Data Center

Same steps, but use your Jira Server URL (e.g. https://jira.yourcompany.com) and a personal access token.

Multiple Jira servers

Team and Enterprise plans support multiple Jira server connections. Each team can be assigned to a different server.

Main Dashboard

Real-time overview of your Jira project.

How it works

Enter a JQL query or select a saved query from the dropdown. The dashboard fetches matching issues and groups them by epic.

What you see

• Stats bar — Total issues, done, in progress, to do, overdue, stale, unassigned
• Epic cards — Each epic shows progress bar, issue count, urgency flags, due dates
• Issue rows — Individual issues with status, assignee, priority, flags, comments
• Quick filters — Filter by All, Critical, Overdue, or Stale

Urgency flags

Flag	Severity	Meaning
Overdue	Critical	Due date has passed
Due soon	Warning	Due within 3 days
Stale	Warning	No update in 7+ days
Unassigned	Warning	No assignee set
No estimate	Info	Missing story points

Auto-refresh

Toggle the Auto-refresh checkbox to reload data every 60 seconds.

Analytics

Status distribution, quality scores, and AI-powered insights.

Features

• Status distribution — Pie/bar charts showing To Do vs In Progress vs Done
• Assignee workload — Issues per team member
• Priority breakdown — Issues by priority level
• AI Coach panel — Ask questions about your project data

JQL Queries & Bookmarks

Save and reuse your favorite JQL queries.

JQL search bar

The search bar at the top of the dashboard accepts any valid JQL query. Press Enter or click Search to execute.

Example queries

project = DEMO ORDER BY status ASC, updated DESC
project = DEMO AND sprint in openSprints()
project = DEMO AND assignee = currentUser()
project = DEMO AND status != Done AND duedate < now()

Bookmarks

Save frequently used queries as bookmarks. Click the bookmark icon next to the search bar to save the current query.

Quick queries

The dropdown shows pre-built queries for each configured project and team, plus your saved bookmarks.

Project Health

Automated board quality assessment and compliance scoring.

How it works

The compliance engine analyzes your project against a set of checks and produces a score from 0-100.

Checks include

• All issues have descriptions and acceptance criteria
• Stories have estimates (story points)
• Issues have assignees
• Due dates are set for upcoming work
• RACI matrix is documented
• Cross-team dependencies are tracked
• WIP limits are respected
• Stale issues are flagged

Suggest Fix

Each failed check includes an AI-generated "Suggest Fix" button that provides a recommended action to improve the score.

Definition of Ready

Check if issues are ready for sprint planning.

Checks

Each issue is scored against these criteria:

• Has a description (>30 characters)
• Has acceptance criteria
• Has a due date
• Has an assignee
• Has story points or time estimate
• Has priority set (not Medium/default)
• Has epic or labels for context

Issues scoring 70%+ are considered "Ready". The page shows distribution and the most common missing criteria.

Backlog Coach

AI-powered backlog review and refinement suggestions.

The Backlog Coach page loads your issues and provides an AI analysis panel. Use the pre-built prompts or ask custom questions about your backlog:

• Which items should be prioritized?
• Are there duplicate or overlapping stories?
• What's missing from the backlog for the next sprint?

Hierarchy View

Navigate your issue tree: epics, stories, subtasks.

Visualizes the parent-child relationships between issues. Expand epics to see their stories, expand stories to see subtasks. Includes stats at each level (done/total, story points).

Sprint Planning

Plan sprints with capacity and priority awareness.

Shows current and upcoming sprints from your Jira board. Displays team capacity, issue assignments, and helps balance workload across the sprint.

Prioritization

AI-assisted issue ranking based on value and urgency.

Analyzes issues using multiple signals (priority, due date, dependencies, staleness) and produces a ranked list. The AI can also generate a prioritization rationale.

Sprint Goals

Define and track sprint-level objectives.

How to use

1. Click New Sprint Goals
2. Enter a sprint name and add goals
3. Link Jira issues to each goal
4. Track status: Not Started, In Progress, Achieved, Missed

Sprint goals persist across sessions and can be reviewed in Sprint Review.

Daily Standup

Auto-generated standup report from Jira activity.

Pulls recent changes from Jira (last 24h by default) and groups them by team member:

• What was done — Issues moved to Done or transitioned forward
• What's in progress — Currently assigned and active
• Blockers — Flagged or stale issues

Flow Metrics

Cumulative flow, cycle time, and throughput analysis.

Cumulative Flow Diagram (CFD)

Shows how issues move through statuses over time. Helps identify bottlenecks (widening bands = work piling up).

Cycle Time

Measures how long issues take from "In Progress" to "Done". Shows percentiles (P50, P85, P95) and individual data points.

Flow Efficiency

Ratio of active work time vs wait time. Higher is better.

Sprint Review

What was completed, velocity trends, and burndown.

Summarizes the sprint: completed vs committed work, velocity compared to previous sprints, and a burndown chart.

Retrospective

Collaborative retro boards with voting.

How to use

1. Create a new retro session
2. Team members add entries in categories: Went Well, To Improve, Action Items, Questions, Shoutouts
3. Vote on entries to prioritize discussion
4. Review and create action items

Gantt Chart

Timeline view of issues with dependencies.

Displays issues on a timeline based on created date and due date. Shows dependencies as arrows between bars.

Dependencies

Map and discover cross-issue and cross-project dependencies.

Dependency view

Shows all issue links (blocks, is blocked by, relates to) as a network graph.

Auto-discover

The Discover Dependencies feature scans multiple projects for cross-project links, shared assignees, and overlapping components — even if no explicit Jira links exist.

PI Board

Multi-team Program Increment planning and tracking.

Overview

Aggregates all configured teams into a single view showing:

• Per-team progress (done/total, story points)
• Cross-team dependencies
• Program board (features across teams and sprints)
• PI compliance score

Configuration

Set up PI dates, sprint count, and sprint duration in Settings. Assign teams to projects and servers.

ROAM Board

Risk and impediment tracking for PI planning.

Categories

Category	Meaning
Resolved	Risk eliminated
Owned	Someone is responsible for managing it
Accepted	Acknowledged, no action needed
Mitigated	Actions taken to reduce impact

Add risks with title, description, severity (low/medium/high/critical), owner, and linked Jira issues.

Team Health Check

Anonymous team sentiment surveys.

How it works

1. Create a health check session
2. Team members vote (1-5) on categories: Mission, Speed, Quality, Fun, Learning, Support, Communication, Autonomy
3. Optional comments per category
4. View aggregated results with green/yellow/red distribution

RACI Matrix

Document team responsibilities and validate assignments.

Creating a RACI matrix

1. Click Create from Template (Project or PI template)
2. Click cells to cycle through: Responsible, Accountable, Consulted, Informed
3. Add custom activities and roles as needed

Validation

The validator checks:

• Every activity has exactly one Accountable (A)
• Every activity has at least one Responsible (R)
• No role is Accountable for too many activities (overload)

AI Suggestions

The Suggest RACI feature analyzes your Jira data to recommend responsibility assignments based on who works on what.

Expertise Map

Discover who knows what across your team.

Analyzes issue history to build a skill/expertise map: who has worked on which components, labels, and issue types. Helps identify SMEs (Subject Matter Experts) and knowledge silos.

AI Coach

AI-powered insights for your project data.

How it works

The AI Coach appears on the Dashboard and Analytics pages. It builds a prompt from your Jira data and sends it to your configured AI provider.

Pre-built prompts

• Full Project Summary — Comprehensive status report covering all epics
• Progress Report — What's done, what's in progress, what's next
• Risks & Blockers — Overdue, stale, and unassigned items
• Upcoming Work — What the team should focus on next
• Epic Health — Per-epic analysis

Copy/paste mode

If no AI provider is configured, the app generates the prompt text. Copy it into ChatGPT, Claude, or any LLM and paste the response back.

Direct integration

Configure an AI provider in Settings to get responses directly in the app (requires Team or Enterprise plan).

AI Provider Setup

Connect your own AI model.

Supported providers

Provider	What you need
OpenAI	API key from platform.openai.com
Anthropic (Claude)	API key from console.anthropic.com
Ollama	Local Ollama instance URL (e.g. http://localhost:11434)
Custom	Any HTTP endpoint that accepts prompts (n8n, Make, Zapier, your own server)

Configuration

Go to Settings → scroll to AI Provider section. Enter your provider, model, and API key. Click Save.

Custom AI Endpoint

The Custom provider lets you connect any HTTP endpoint as your AI backend. This is ideal for:

• n8n workflows — build a webhook that processes prompts through your own AI pipeline
• Make/Zapier — trigger automations with AI responses
• Internal AI services — connect to your company's private LLM or RAG system
• AI agents — any agentic endpoint that accepts a prompt and returns text

Endpoint contract

Your endpoint must accept a POST request with this JSON body:

{
  "prompt": "Analyze this project data...",
  "context": "AIgileCoach agile coaching dashboard",
  "model": "your-model-name",
  "messages": [
    { "role": "system", "content": "You are an agile coach assistant..." },
    { "role": "user", "content": "Analyze this project data..." }
  ]
}

Your endpoint can return any of these formats:

// Any of these work:
{ "response": "Your analysis..." }
{ "text": "Your analysis..." }
{ "content": "Your analysis..." }
{ "output": "Your analysis..." }                    // n8n webhook
{ "choices": [{ "message": { "content": "..." } }] } // OpenAI-compatible
"Plain text response"                                // Raw text

Setup example (n8n)

1. Create an n8n workflow with a Webhook trigger node
2. Add your AI processing nodes (OpenAI, Claude, local LLM, etc.)
3. Return the response as JSON: { "response": "..." }
4. In AIgileCoach Settings, set provider to Custom
5. Enter the n8n webhook URL as the endpoint
6. Optionally add an API key for authentication

Security

• SSRF protection — the app blocks requests to private IPs (10.x, 172.x, 192.168.x), localhost, and cloud metadata endpoints
• Timeout — requests abort after 30 seconds
• Response size limit — 100KB max to prevent memory abuse
• HTML sanitization — HTML tags are stripped from responses to prevent XSS

Settings

Configure Jira servers, teams, and application behavior.

Jira Servers

Add, edit, or remove Jira server connections. Each server needs a URL, email, and API token.

Teams

Define teams and assign them to Jira servers and projects. Each team can have a custom JQL query and color.

Teams vs Projects — what's the difference?

A Jira Project is where issues live in Jira (e.g. BACKEND, MOBILE). A Team in AIgileCoach represents a group of people and links them to a Jira project and server.

Real world	Jira	AIgileCoach
Backend team	Project BACKEND	Team "Backend" → linked to project BACKEND on server "Jira Cloud"
Mobile team	Project MOBILE	Team "Mobile" → linked to project MOBILE
Platform team (2 repos)	Projects INFRA + DEVOPS	Team "Platform" → linked to project INFRA (primary)

JQL Template

Customize how the app finds epic children. Options: auto-detect, parent field (Jira 10+), Epic Link (classic), label-based, component-based.

Import / Export

Export your configuration as JSON for backup. Import to restore or migrate between environments.

Billing & Plans

Manage your subscription (SaaS only).

Plans

Feature	Free	Team ($29/mo)	Enterprise ($149/mo)
Jira servers	1	3	Unlimited
Users	1	10	Unlimited
Teams	1	10	Unlimited
AI integration	Copy/paste	Full	Full
PI Planning	No	Yes	Yes
Compliance	No	Yes	Yes
SSO/SAML	No	No	Yes
Audit log	No	No	Yes
Custom domain	No	No	Yes
Priority support	No	No	Yes
On-premise option	No	No	Yes

Team vs Enterprise — who is each plan for?

	Team	Enterprise
Who buys it	Team lead or scrum master	IT procurement / CTO
Decision maker	Individual with a credit card	Needs approval, legal, security review
Payment	Self-serve, monthly via Stripe	Self-serve or annual invoice
Support	Email	Dedicated, SLA
Deployment	SaaS only	SaaS or on-premise

Upgrading

Go to Settings → Billing & Plan section. Click the upgrade button — you'll be redirected to Stripe Checkout to enter payment details.

Managing subscription

Click Manage Subscription to open the Stripe Customer Portal where you can update payment method, change plan, view invoices, or cancel.

Health Monitoring

System and tenant health status.

Endpoints

URL	Auth	Shows
GET /health	None	API server, database, deployment mode
GET /tenant/health	Bearer token	Jira servers, AI config, RACI, config persistence
GET /tenant/health?all=true	Admin token	All tenants' health checks

Frontend health page

Visit /health in the app for a visual status dashboard with auto-refresh every 30 seconds.

Performance Settings

Control caching and query limits.

Settings

Setting	Default	Description
cacheEnabled	true	Enable in-memory caching of Jira search results
cacheTtlMinutes	5	How long cached results stay valid
maxIssuesPerQuery	500	Maximum issues fetched per JQL query

How caching works

When you run a JQL query, results are cached in memory. Subsequent requests with the same query return instantly from cache until the TTL expires. The cache is per-tenant in SaaS mode.

Result truncation

If a query matches more issues than maxIssuesPerQuery, only the first N issues are fetched. An amber banner appears: "Showing 500 of 12,847 issues." Narrow your JQL query for better results.

Manual refresh

Click the Refresh button on the dashboard to bypass the cache and fetch fresh data from Jira.

API Reference

REST API endpoints for integration and automation.

Authentication

SaaS mode requires a Bearer token in the Authorization header. Get a token via POST /auth/login.

curl -H "Authorization: Bearer YOUR_TOKEN" https://api.aigilecoach.io/config/status

Key endpoints

Method	Path	Description
POST	/auth/register	Register new tenant + admin user
POST	/auth/login	Login, returns JWT token
GET	/config/status	Configuration overview
GET	/config	Full configuration (servers, teams, PI)
POST	/config	Update configuration
GET	/issues?jql=...	Fetch issues by JQL
GET	/settings	App settings
POST	/settings	Update settings
GET	/health	System health check
GET	/tenant/health	Tenant health (auth required)
GET	/billing/status	Current plan and subscription
GET	/billing/limits	Plan limits and usage
POST	/billing/checkout	Create Stripe Checkout session
POST	/billing/portal	Open Stripe Customer Portal
GET	/audit	Query audit log (enterprise, admin)
GET	/license/status	License key info (on-premise)

Audit Log

Track who did what, when — enterprise only.

What gets logged

Every mutating action (POST, PUT, DELETE) by authenticated users is automatically recorded:

• Configuration changes (servers, teams, settings)
• User management (invites, role changes)
• Billing actions (plan changes)
• AI config updates

Viewing the audit log

Admin users can query the audit log via the API:

GET /audit?page=1&limit=50
GET /audit?action=POST&user=alice@company.com

Response

{
  "total": 142,
  "page": 1,
  "limit": 50,
  "entries": [
    {
      "id": "...",
      "action": "POST /config",
      "resource": "server-123",
      "userEmail": "alice@company.com",
      "details": { "statusCode": 200 },
      "ipAddress": "192.168.1.10",
      "createdAt": "2026-03-29T10:30:00Z"
    }
  ]
}

Filtering

Parameter	Description	Example
page	Page number (default: 1)	?page=2
limit	Results per page (max: 200)	?limit=100
action	Filter by action (partial match)	?action=DELETE
user	Filter by user email (exact)	?user=alice@co.com

Data & Privacy

What data AIgileCoach stores, and what it doesn't.

What we store

Data	Where	Encryption	Purpose
Email & password hash	Database	bcrypt (password)	Authentication
Tenant name & plan	Database	No (not sensitive)	Account management
Jira server URL	Database	No	Server connection
Jira username	Database	No	API authentication
Jira API token	Database	AES-256-GCM	API authentication
AI provider API key	Database (JSON)	Application-level	AI integration
Settings & bookmarks	Database	No (not sensitive)	User preferences
Stripe customer ID	Database	No	Billing
Audit log (enterprise)	Database	No	Compliance tracking

What we do NOT store

All Jira data is:

1. Fetched in real-time from your Jira instance on each request
2. Returned directly to your browser
3. Never persisted to disk or database

The only exception is a short-lived in-memory cache (default 5 minutes) that holds recent search results in RAM. This cache:

• Is never written to disk
• Is lost on server restart
• Is scoped per tenant (other tenants cannot access your cached data)
• Can be disabled in Settings (Performance → Cache Enabled)

Collaborative features (in-memory only)

Data from these features is stored in server memory, not in the database:

Feature	Data	Persistence
Retrospectives	Entries, votes	Lost on restart
ROAM risks	Risk items	Lost on restart
Team health checks	Votes, scores	Lost on restart
Sprint goals	Goals, status	Lost on restart
RACI matrices	Assignments	Lost on restart

In SaaS mode, this data is isolated per tenant using namespaced keys.

Security measures

• Jira tokens encrypted at rest with AES-256-GCM
• Passwords hashed with bcrypt (10 rounds)
• JWT tokens signed with HS256, 7-day expiry
• HTTPS enforced via Let's Encrypt on all domains
• Tenant isolation — all queries scoped by tenant ID, no cross-tenant access
• API keys never exposed in responses (masked as ••••••••)

On-premise deployments

For enterprise on-premise: no data ever leaves your network. Everything runs on your infrastructure — database, API, frontend. AIgileCoach servers are never contacted (license validation is offline).

Data deletion

To delete all your data:

• SaaS: Contact contact@aigilecoach.io — we delete your tenant and all associated data within 48 hours
• On-premise: Stop containers and delete the database volume: docker compose down -v

Observability

Monitor, measure, and audit your AIgileCoach deployment.

Stack overview

AIgileCoach ships with a full observability stack covering four pillars:

Pillar	What it provides	Tools
Metrics	HTTP request rates, latencies, error rates, DB pool, Node.js runtime stats	Prometheus, Grafana, OTLP
Alerting	Built-in alert rules for error spikes, high latency, resource exhaustion	Email, admin dashboard
Audit log	Immutable record of all mutating actions (who did what, when)	REST API, admin UI
Error tracking	Structured error logs with request context and stack traces	Structured logger, OTLP export

Monitoring endpoints

Endpoint	Format	Auth	Description
GET /metrics	Prometheus text	Service token (metrics:read)	All application metrics in Prometheus exposition format
GET /metrics/json	JSON	Service token (metrics:read)	Same metrics as JSON for custom integrations
POST /metrics/otlp	OTLP JSON	Service token (metrics:read)	Push-based export to OpenTelemetry Collector
GET /health	JSON	None (public)	Basic system health: API up, DB connected, deployment mode
GET /tenant/health	JSON	JWT (logged-in user)	Tenant-specific health: Jira, AI provider, config
GET /admin/audit-log	JSON	JWT (admin) + Enterprise	Query the audit log
GET /admin/alerts	JSON	JWT (admin)	View active and recent alerts

Architecture

                         +------------------+
                         |   AIgileCoach    |
                         |   (API server)   |
                         +--------+---------+
                                  |
                  +---------------+---------------+
                  |               |               |
           GET /metrics    POST /metrics/otlp   Alerts
                  |               |               |
        +---------+---+   +------+-------+   +---+----------+
        |  Prometheus |   |  OTLP        |   | Email        |
        |  (scrape)   |   |  Collector   |   | (SMTP)       |
        +------+------+   +------+-------+   +--------------+
               |                  |
        +------+------+   +------+-------+
        |   Grafana   |   | Datadog /    |
        | (dashboards)|   | Splunk /     |
        +-------------+   | New Relic /  |
                          | Jaeger       |
                          +--------------+

SaaS Monitoring

What you get as a SaaS customer — no setup required.

What's available by plan

Feature	Free	Team	Enterprise
System health page (/health)	Yes	Yes	Yes
Tenant health (/tenant/health)	Yes	Yes	Yes
Usage & performance stats	Yes	Yes	Yes
Jira connection permissions	Yes	Yes	Yes
Email notifications	Limited	Yes	Yes
Service tokens (for external tools)	No	Yes	Yes
Audit log	No	No	Yes
Prometheus / OTLP export	No	Yes	Yes

Built-in monitoring (all plans)

Every SaaS customer gets these features in the app — no external tools needed:

1. Usage & Performance (Settings page)

Go to Settings and scroll to Usage & Performance. You'll see:

• Requests (24h) — total API calls made by your tenant
• Errors (24h) — failed requests with error rate percentage
• Jira calls — how many calls were made to your Jira servers
• Jira health — green/red indicator for Jira connectivity
• 7-day bar chart — daily request volume with error overlay

2. Tenant Health Check

Visit /health in the app or call the API directly:

# System health (public)
curl https://api.aigilecoach.io/health

# Your tenant health (requires auth)
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.aigilecoach.io/tenant/health

Shows: Jira server connectivity (per server, with latency), AI provider status, configuration health, RACI status.

3. Jira Token Permissions

Go to Settings and scroll to Jira Permissions. The app tests your Jira API token against 8 capabilities (read issues, write issues, manage sprints, admin, etc.) and shows green/red for each.

4. Email Notifications

Go to Settings → Notifications to configure which alerts you receive:

Notification	When it fires
Payment succeeded	After each successful payment
Payment failed	When Stripe can't charge your card
Trial ending	3 days before your trial expires
Ticket quality alert	Jira tickets missing descriptions, estimates, or overdue (checked every 6h)
Weekly digest	Monday summary of project activity

Each notification type can be toggled on/off individually. Add extra email recipients for team-wide alerts.

Advanced monitoring (Team & Enterprise)

5. Service Tokens

Create API tokens for external monitoring tools. Go to Settings → Service Tokens.

Use these to connect your own Prometheus, Grafana, Datadog, or any monitoring tool to AIgileCoach:

# Create a token in Settings, then use it:
curl -H "Authorization: Bearer svc_abc123..." \
  https://api.aigilecoach.io/metrics/prometheus

# Or for OpenTelemetry format:
curl -H "Authorization: Bearer svc_abc123..." \
  https://api.aigilecoach.io/metrics/otlp

6. Prometheus & Grafana Integration

If your team already uses Prometheus/Grafana, add AIgileCoach as a scrape target:

# prometheus.yml
scrape_configs:
  - job_name: aigilecoach
    scrape_interval: 30s
    metrics_path: /metrics/prometheus
    authorization:
      credentials: "svc_your_token_here"
    static_configs:
      - targets: ["api.aigilecoach.io"]

See the Prometheus & Grafana section for the full list of exported metrics and example Grafana queries.

7. OpenTelemetry Integration

For teams using OpenTelemetry Collector, Datadog, Splunk, or New Relic:

# otel-collector pipeline
receivers:
  otlp/aigilecoach:
    protocols:
      http:
        endpoint: "https://api.aigilecoach.io/metrics/otlp"
        headers:
          authorization: "Bearer svc_your_token_here"

See the OpenTelemetry section for full collector configuration.

Enterprise-only monitoring

8. Audit Log

Enterprise plans include a full audit trail of all actions. Go to Settings → Audit Log to view:

• Who changed what, when, from which IP
• Configuration changes, user management, billing actions
• Filterable by action type and user
• API access: GET /audit?page=1&limit=50

See the Audit Log section for API details.

What we monitor for you

As the platform operator, we proactively monitor your tenant's health:

Check	Frequency	Action
Jira server connectivity	Every 6 hours	Email alert if unreachable
Ticket quality scan	Every 6 hours	Email alert for missing info, overdue items
Error rate spike	Every 60 seconds	Internal alert, proactive investigation
API latency degradation	Every 60 seconds	Internal alert
Payment failures	Real-time (webhook)	Email notification immediately

Summary: who needs what

If you want to...	Use this	Plan
See if AIgileCoach is working	/health page	All
Check your Jira connection	Settings → Jira Permissions	All
See your usage stats	Settings → Usage & Performance	All
Get email alerts	Settings → Notifications	All
Connect Prometheus/Grafana	Service Token + /metrics/prometheus	Team+
Connect Datadog/Splunk/etc	Service Token + /metrics/otlp	Team+
See who did what	Settings → Audit Log	Enterprise
Run your own monitoring stack	Observability Kit (on-premise)	Enterprise on-prem

Prometheus & Grafana

Scrape metrics and build dashboards for your AIgileCoach deployment.

Exported metrics

AIgileCoach exposes the following metrics at /metrics:

Metric	Type	Labels	Description
aigilecoach_http_requests_total	Counter	method, route, status	Total HTTP requests handled
aigilecoach_http_request_duration_seconds	Histogram	method, route	Request latency in seconds (buckets: 0.01 to 30s)
aigilecoach_http_errors_total	Counter	method, route, error_type	Requests that returned 4xx/5xx
aigilecoach_jira_requests_total	Counter	method, status	Outbound requests to Jira
aigilecoach_jira_request_duration_seconds	Histogram	method	Jira API call latency
aigilecoach_ai_requests_total	Counter	provider, status	Requests to AI providers
aigilecoach_ai_token_usage_total	Counter	provider, direction	AI token usage (prompt/completion)
aigilecoach_db_pool_active	Gauge		Active database connections
aigilecoach_db_pool_idle	Gauge		Idle database connections
aigilecoach_db_pool_waiting	Gauge		Queries waiting for a connection
aigilecoach_active_tenants	Gauge		Number of tenants with activity in the last 15 minutes
aigilecoach_cache_hits_total	Counter		In-memory cache hits
aigilecoach_cache_misses_total	Counter		In-memory cache misses
nodejs_heap_size_bytes	Gauge	space	V8 heap memory usage
nodejs_eventloop_lag_seconds	Gauge		Event loop lag
process_cpu_seconds_total	Counter		CPU time consumed
process_resident_memory_bytes	Gauge		Resident set size

Prometheus configuration

Add the following scrape job to your prometheus.yml:

# prometheus.yml
scrape_configs:
  - job_name: 'aigilecoach'
    scrape_interval: 15s
    metrics_path: /metrics
    scheme: https                          # use 'http' for local/dev
    authorization:
      type: Bearer
      credentials: 'svc_your_service_token_here'
    static_configs:
      - targets: ['api.aigilecoach.io']
        labels:
          environment: 'production'

    # Optional: relabel to shorten instance label
    relabel_configs:
      - source_labels: [__address__]
        target_label: instance
        replacement: 'aigilecoach'

Grafana setup

1. Add your Prometheus instance as a data source in Grafana (Configuration → Data Sources → Prometheus)
2. Create a new dashboard or import the AIgileCoach starter dashboard
3. Add panels using the queries below

Example Grafana queries

Request rate (requests/sec):

rate(aigilecoach_http_requests_total[5m])

Error rate (%):

100 * rate(aigilecoach_http_errors_total[5m])
  / rate(aigilecoach_http_requests_total[5m])

P95 latency by route:

histogram_quantile(0.95,
  rate(aigilecoach_http_request_duration_seconds_bucket[5m])
) by (route)

Jira API latency (P50 vs P95):

histogram_quantile(0.50, rate(aigilecoach_jira_request_duration_seconds_bucket[5m]))
histogram_quantile(0.95, rate(aigilecoach_jira_request_duration_seconds_bucket[5m]))

DB pool saturation:

aigilecoach_db_pool_waiting > 0

Memory usage:

process_resident_memory_bytes{job="aigilecoach"} / 1024 / 1024

Cache hit rate (%):

100 * rate(aigilecoach_cache_hits_total[5m])
  / (rate(aigilecoach_cache_hits_total[5m]) + rate(aigilecoach_cache_misses_total[5m]))

OpenTelemetry

Export metrics to any OTLP-compatible backend.

OTLP endpoint

AIgileCoach exposes an OTLP-compatible JSON endpoint for push-based metric collection:

POST /metrics/otlp
Authorization: Bearer svc_your_service_token_here
Content-Type: application/json

The endpoint returns metrics in OTLP JSON format, suitable for ingestion by the OpenTelemetry Collector or any OTLP-compatible backend.

OpenTelemetry Collector configuration

Configure the OTLP Collector to scrape AIgileCoach metrics and forward them to your backend:

# otel-collector-config.yaml
receivers:
  prometheus:
    config:
      scrape_configs:
        - job_name: 'aigilecoach'
          scrape_interval: 15s
          metrics_path: /metrics
          scheme: https
          authorization:
            type: Bearer
            credentials: 'svc_your_service_token_here'
          static_configs:
            - targets: ['api.aigilecoach.io']

processors:
  batch:
    timeout: 10s
    send_batch_size: 1024

  resource:
    attributes:
      - key: service.name
        value: aigilecoach
        action: upsert

exporters:
  # Grafana Cloud
  otlphttp/grafana:
    endpoint: https://otlp-gateway-prod-us-central-0.grafana.net/otlp
    headers:
      Authorization: 'Basic <base64-encoded-credentials>'

  # Datadog
  datadog:
    api:
      key: '${DATADOG_API_KEY}'
      site: datadoghq.com

  # Splunk
  splunk_hec:
    token: '${SPLUNK_HEC_TOKEN}'
    endpoint: https://splunk-hec.yourcompany.com:8088

  # New Relic
  otlphttp/newrelic:
    endpoint: https://otlp.nr-data.net:4318
    headers:
      api-key: '${NEW_RELIC_LICENSE_KEY}'

  # Jaeger (for trace-compatible backends)
  otlp/jaeger:
    endpoint: jaeger-collector:4317
    tls:
      insecure: true

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [batch, resource]
      exporters: [otlphttp/grafana]        # choose your exporter(s)

Supported backends

Backend	Exporter	Notes
Grafana Cloud	otlphttp	Use OTLP gateway endpoint with Basic auth
Datadog	datadog	Requires API key; set site for EU regions
Splunk	splunk_hec	Uses HEC token; supports metrics and logs
New Relic	otlphttp	Use api-key header with license key
Jaeger	otlp	Native OTLP ingestion on port 4317
Any OTLP backend	otlphttp / otlp	Standard OTLP protocol over HTTP or gRPC

Service Tokens

Authenticate monitoring tools and CI/CD pipelines without user credentials.

What are service tokens?

Service tokens are long-lived API credentials designed for machine-to-machine authentication. They allow tools like Prometheus, Grafana, and CI pipelines to access AIgileCoach endpoints without a user session or JWT.

Creating a service token

1. Go to Settings → Service Tokens (admin only)
2. Click Create Token
3. Enter a descriptive name (e.g. "Prometheus production")
4. Select the required scopes
5. Optionally set an expiry date
6. Click Generate — the token is shown once; copy it immediately

Available scopes

Scope	Grants access to	Typical consumer
metrics:read	/metrics, /metrics/json, /metrics/otlp	Prometheus, OTLP Collector, Grafana
health:read	/health, /tenant/health	Uptime monitors, load balancers
alerts:read	/admin/alerts	PagerDuty, Opsgenie integrations
audit:read	/admin/audit-log	SIEM, compliance tools
admin:full	All admin endpoints	CI/CD, automation scripts

Using service tokens

Pass the token in the Authorization header:

# curl
curl -H "Authorization: Bearer svc_abc123..." https://api.aigilecoach.io/metrics

# Prometheus (prometheus.yml)
authorization:
  type: Bearer
  credentials: 'svc_abc123...'

# Grafana (data source config)
# Set "Custom HTTP Headers" → Authorization: Bearer svc_abc123...

Security best practices

• Minimal scopes — Only grant the scopes each consumer needs. Prometheus only needs metrics:read.
• Set expiry dates — Rotate tokens regularly. Set expiry to 90 days and create a new token before it expires.
• One token per consumer — Create separate tokens for Prometheus, Grafana, CI, etc. If one is compromised, revoke it without affecting others.
• Store securely — Keep tokens in environment variables or a secrets manager (Vault, AWS Secrets Manager, etc.). Never commit tokens to version control.
• Audit usage — Service token activity is logged in the audit log (enterprise). Review regularly for unexpected access patterns.
• Revoke unused tokens — Periodically review active tokens in Settings and revoke any that are no longer needed.

Managing tokens via API

# List all service tokens (admin JWT required)
curl -H "Authorization: Bearer <admin-jwt>" \
  https://api.aigilecoach.io/admin/service-tokens

# Revoke a token
curl -X DELETE \
  -H "Authorization: Bearer <admin-jwt>" \
  https://api.aigilecoach.io/admin/service-tokens/TOKEN_ID

Alerting

Built-in alert rules that notify you when something goes wrong.

How alerting works

AIgileCoach evaluates alert rules on every metric collection cycle (every 60 seconds). When a rule's threshold is breached, the system:

1. Records the alert with timestamp, severity, and context
2. Sends an email notification to ADMIN_EMAIL (if configured)
3. Displays the alert in the admin dashboard (Settings → Health Monitoring)
4. Enters a cooldown period to avoid alert fatigue

Built-in alert rules

Rule	Condition	Severity	Cooldown
High error rate	5xx error rate > 5% over 5 minutes	Critical	15 min
High latency	P95 response time > 5s over 5 minutes	Warning	15 min
Memory pressure	Heap usage > 512 MB	Warning	30 min
DB pool exhaustion	Waiting queries > 0 for > 30 seconds	Critical	10 min
Jira connection failure	3+ consecutive Jira API failures	Critical	15 min
AI provider errors	AI request failure rate > 50%	Warning	15 min
Event loop lag	Event loop lag > 500ms	Warning	30 min

Configuring alert delivery

Set the following environment variables to enable email alerts:

Variable	Description	Example
ADMIN_EMAIL	Recipient for alert emails	ops@yourcompany.com
SMTP_HOST	SMTP server hostname	smtp.gmail.com
SMTP_PORT	SMTP port	587
SMTP_USER	SMTP username	alerts@yourcompany.com
SMTP_PASS	SMTP password or app-specific password

If ADMIN_EMAIL is not set, alerts are still recorded and visible in the admin dashboard but no emails are sent.

Viewing alerts

# Via API (admin JWT required)
curl -H "Authorization: Bearer <admin-jwt>" \
  https://api.aigilecoach.io/admin/alerts

# Response
{
  "alerts": [
    {
      "id": "alert_abc123",
      "rule": "high_error_rate",
      "severity": "critical",
      "message": "5xx error rate is 8.2% (threshold: 5%)",
      "firedAt": "2026-03-29T14:30:00Z",
      "resolvedAt": null,
      "acknowledged": false
    }
  ],
  "total": 1
}

Cooldown periods

After an alert fires, it enters a cooldown period during which the same rule will not fire again. This prevents alert fatigue from repeated notifications for ongoing issues. Once the cooldown expires, the rule is re-evaluated and will fire again if the condition persists.

Audit Log

Immutable record of all mutating actions for compliance and forensics.

What gets logged

Every mutating action (create, update, delete) is recorded with full context:

• Authentication events — login, logout, failed login attempts
• Settings changes — Jira connection updates, AI provider config, team management
• Service tokens — creation, revocation, scope changes
• Billing events — plan upgrades, downgrades, payment method changes
• User management — user creation, role changes, deactivation
• Data exports — CSV/PDF exports of dashboards and reports

Read-only actions (viewing dashboards, running JQL queries) are not logged to keep the audit log focused and manageable.

Querying the audit log

# Get recent entries
GET /admin/audit-log
Authorization: Bearer <admin-jwt>

# Filter by action type
GET /admin/audit-log?action=settings.update

# Filter by user
GET /admin/audit-log?userId=user_abc123

# Filter by date range
GET /admin/audit-log?from=2026-03-01&to=2026-03-29

# Combine filters with pagination
GET /admin/audit-log?action=auth.login&from=2026-03-01&limit=50&offset=0

Response format

{
  "entries": [
    {
      "id": "aud_789xyz",
      "timestamp": "2026-03-29T10:15:30Z",
      "tenantId": "tenant_abc",
      "userId": "user_abc123",
      "userEmail": "admin@yourcompany.com",
      "action": "settings.jira.update",
      "resource": "jira_server",
      "resourceId": "srv_456",
      "details": {
        "field": "base_url",
        "oldValue": "https://old-jira.company.com",
        "newValue": "https://jira.company.com"
      },
      "ip": "203.0.113.42",
      "userAgent": "Mozilla/5.0 ..."
    }
  ],
  "total": 1284,
  "limit": 50,
  "offset": 0
}

Audit log entry fields

Field	Type	Description
id	String	Unique entry identifier
timestamp	ISO 8601	When the action occurred
tenantId	String	Tenant that owns the entry
userId	String	User who performed the action
userEmail	String	Email of the user
action	String	Dot-notation action type (e.g. settings.jira.update)
resource	String	Type of resource affected
resourceId	String	ID of the affected resource
details	Object	Action-specific data (old/new values, etc.)
ip	String	Client IP address
userAgent	String	Client user agent string

Retention

Audit log entries are retained for 1 year on SaaS plans. On-premise deployments retain entries indefinitely (limited only by database storage). Entries are immutable and cannot be edited or deleted through the API.

Enterprise SaaS

Enterprise features on the hosted AIgileCoach platform.

What's included

Enterprise SaaS is the same hosted platform as the Team plan, with additional features:

• Unlimited Jira servers, users, teams, RACI matrices
• SSO/SAML — Single sign-on integration (coming soon)
• Audit log — Full activity tracking for compliance
• Custom domain — Use aigile.yourcompany.com via CNAME
• Priority support — Dedicated email, SLA-backed response times

How to upgrade

1. Go to Settings → Billing
2. Click Enterprise — $149/mo
3. Complete payment via Stripe Checkout
4. Enterprise features are enabled immediately

Custom domain setup

1. Contact contact@aigilecoach.io with your desired domain
2. Add a CNAME record: aigile.yourcompany.com → app.aigilecoach.io
3. We configure SSL and routing on our side

SSO/SAML (coming soon)

Enterprise tenants will be able to configure SAML 2.0 SSO with their identity provider (Okta, Azure AD, Google Workspace, etc.). Contact us for early access.

On-Premise Setup

Run AIgileCoach on your own infrastructure.

When to choose on-premise

• Security policy requires data to stay on your network
• Regulatory requirements (data residency, compliance)
• Air-gapped or restricted network environments

Prerequisites

• Docker and Docker Compose installed
• A valid enterprise license key (contact contact@aigilecoach.io)
• Minimum: 2 CPU, 4 GB RAM, 20 GB disk

Installation

# 1. Authenticate with the private registry (token provided with your license)
echo "YOUR_REGISTRY_TOKEN" | docker login ghcr.io -u gruion --password-stdin

# 2. Download the enterprise compose file
curl -O https://raw.githubusercontent.com/gruion/AIgileCoach/main/docker-compose.enterprise.yml
curl -O https://raw.githubusercontent.com/gruion/AIgileCoach/main/.env.enterprise.example

# 3. Configure
cp .env.enterprise.example .env
# Edit .env — add your LICENSE_KEY, REGISTRY_TOKEN, and change passwords

# 4. Pull images and start
docker compose -f docker-compose.enterprise.yml pull
docker compose -f docker-compose.enterprise.yml up -d

# 5. Access
# Frontend: http://localhost:3010
# API:      http://localhost:3011

Configuration

Variable	Required	Description
REGISTRY_TOKEN	Yes	Token to pull private Docker images
LICENSE_KEY	Yes	Enterprise license key
DB_PASSWORD	Yes	PostgreSQL password
JWT_SECRET	Yes	Secret for JWT token signing
ENCRYPTION_KEY	Yes	Secret for Jira token encryption
API_URL	No	How the frontend reaches the API (default: http://localhost:3011)

Custom domain / SSL

Put a reverse proxy (nginx, Caddy, Traefik) in front of the containers. Point your domain to the proxy and configure SSL certificates.

Updating

# Authenticate (if not already)
echo "$REGISTRY_TOKEN" | docker login ghcr.io -u gruion --password-stdin

# Pull latest images and restart
docker compose -f docker-compose.enterprise.yml pull
docker compose -f docker-compose.enterprise.yml up -d

Backup

# Database backup
docker exec aigilecoach-db pg_dump -U aigilecoach aigilecoach > backup.sql

# Restore
cat backup.sql | docker exec -i aigilecoach-db psql -U aigilecoach aigilecoach

License Keys

How enterprise licensing works.

How it works

1. You purchase an enterprise license from contact@aigilecoach.io
2. We generate a signed license key for your organization
3. You set it as LICENSE_KEY in your deployment's environment
4. On startup, the API validates the key cryptographically — no phone-home or internet required
5. Enterprise features are unlocked based on the key's contents

What's in a license key

Field	Description
Tenant name	Your organization name
Plan	Always "enterprise"
Max users	User limit (0 = unlimited)
Features	SSO, audit log, custom domain, priority support
Expiry date	When the license expires (typically 1 year)

Validation

The key is signed with Ed25519 (asymmetric cryptography). The private key is kept by AIgileCoach; the public key is embedded in the application code. Your deployment can verify the license but cannot generate new ones — no shared secret needed.

Validation happens locally on every request — the API does not contact any external server. If the license expires, enterprise features are automatically disabled.

Checking license status

GET /license/status

Returns:

{
  "licensed": true,
  "plan": "enterprise",
  "tenant": "Acme Corp",
  "maxUsers": "unlimited",
  "features": { "sso": true, "auditLog": true, "customDomain": true },
  "expiresAt": "2027-03-29T00:00:00.000Z",
  "daysRemaining": 365
}

Renewal

When your license approaches expiry, contact us for a renewal key. The old key continues working until its expiry date — there's no interruption during renewal.