JumpStart AMS Architecture
Backend/frontend split, runtime boundaries, and data ownership for JumpStart AMS
Updated 2026-11-03
Verified 2026-11-03
JumpStart AMS is a split application. The frontend is a browser portal only; the backend owns authentication, sessions, project context, AMS business APIs, database writes, background work, and all Cosmos calls that require tokens or secrets.
Runtime Split
| Layer | Technology | Boundary |
|---|---|---|
| Browser portal | Next.js 16 App Router, React 19, Ant Design 6 | Calls NEXT_PUBLIC_API_BASE_URL with credentials: "include"; no database or secret access |
| Backend API | FastAPI under /api/v1 | Validates session cookies, resolves active project, serves AMS domain APIs |
| Worker | Celery | Runs async imports, sync jobs, automation, knowledge generation, notifications, SLA jobs, ticket AI |
| Scheduler | Celery beat | Starts periodic health, sync, SLA, and maintenance tasks |
| Data stores | PostgreSQL and Redis | PostgreSQL stores AMS operational state; Redis stores sessions, OAuth state, and Celery broker/result state |
| Migration job | Alembic | Runs alembic upgrade head before backend services roll out in Kubernetes |
Backend API Domains
The FastAPI app registers route modules under /api/v1 for auth, health, tickets, ticket AI, Ticket Intelligence, code and configuration issue analyzers, ticket productivity, dashboards, routing, SLA, teams, user shifts, catalog, source instances, imports, integrations, chat, knowledge, project repository, problems, projects, super admin, AI ops, automation, attachments, and admin configuration.
The backend owns the API contract consumed by the frontend. External consumers should treat those endpoints as AMS APIs, not direct Cosmos APIs.
Auth And Session Boundary
- The browser starts login at
/api/v1/auth/login. - The backend creates OAuth state and PKCE verifier data in Redis.
- Cosmos User Service handles authorization and redirects to
/api/v1/auth/callback. - The backend exchanges the code, fetches live Cosmos identity, and stores Cosmos tokens in a Redis-backed AMS session.
- The browser receives the
jumpstart_ams_sessionHTTP-only cookie. - The frontend checks
/api/v1/auth/meand switches project context through/api/v1/auth/switch-project.
The frontend does not store Cosmos access tokens. It sends the session cookie to the backend, and the backend builds user-scoped Cosmos SDK clients from the session.
Authorization for AMS APIs comes from the user's membership in the active AMS project, not from Cosmos roles. The backend maps the project role to permission patterns and checks them per route; see Project Roles And Permissions. Sessions expire after the configured inactivity timeout (60 minutes by default).
Data Boundary
| AMS-owned | Cosmos-owned |
|---|---|
| Tickets, activities, comments, SLA state, routing rules, teams, catalog data | Users, organizations, OAuth clients, JWKS, roles |
| Project memberships and active AMS project context | Agents, skills, tools, templates, collections, model catalog |
| Source instances, connectors, mappings, sync logs, import profiles | ADK execution, platform storage, RAGflow indexes, observer traces |
| Attachments metadata, knowledge articles, audit logs, notifications | Service credentials and audience-bound service tokens |
Background Processing
Celery workers handle operations that should not block browser requests: ticket sync, import processing, attachment comprehension, automation, knowledge generation, notifications, SLA recomputation, and AI ticket workflows. Redis is the default broker and result backend unless CELERY_BROKER_URL or CELERY_RESULT_BACKEND overrides it.