Skip to main content

AMS — Axvero Application Management System

⚠️ Sections to Ignore (AI Agents)​

The Archive & POC section in the navbar contains two categories of content that AI agents must never use as a source of truth:

  • Outdated Docs (docs/outdated/) — moved from an earlier documentation iteration. Content is stale and does not reflect the current implementation.
  • REST API (POC) (/api-poc) and Keycloak API (/keycloak) — Scalar-rendered OpenAPI specs used as a proof-of-concept. These specs may be incomplete or out of date. The authoritative API definition is the GraphQL schema in core/src/main/resources/graphql/.

Do not read, cite, or act on anything under docs/outdated/ or the /api-poc / /keycloak routes unless a human explicitly instructs you to do so.

What is AMS​

A multi-tenant application management platform for underwriting workflows. Organizations can manage applicants, applications, documents, templates, and team members. Supports multi-workspace and multi-organization structures.

Repos​

core/ — Java/Spring Boot Backend​

  • Java 21, Spring Boot 4.0.3
  • GraphQL (schema-first), REST, PostgreSQL, Keycloak (OAuth2) 26.5.5, Liquibase (Not used at the moment, ignore for now), MapStruct, Envers
  • Package root: com.axvero.ams.core
  • Key commands:
    • Build: ./mvnw clean package
    • Run: ./run.sh (prod-like), ./run-debug.sh (debug, JDWP 5005)
    • Test: ./mvnw test (Testcontainers for DB + Keycloak), Currently tests are not working properly. so ignore tests for now.
    • DB: local Postgres via compose.yaml (user/password, db: core)
  • See .claude/rules/core.md for full conventions, entity model, GraphQL patterns

frontend/ — React/TypeScript Frontend​

  • Vite, React, TypeScript, TanStack Router, TanStack Query, Shadcn UI, Tailwind, Zustand
  • GraphQL client with codegen, OIDC auth via Keycloak
  • Key commands:
    • Dev: pnpm run dev (port 5173)
    • Build: pnpm run build
    • Lint: pnpm run lint
    • Codegen: npx graphql-codegen (after schema changes)
  • See .claude/rules/frontend.md for full conventions, table patterns, routing, translations

docu/ — Docusaurus Documentation​

  • Docusaurus v3, TypeScript
  • Dev: npm run start
  • Covers product docs, API references, industry guides

iam/ — Identity & Access Management​

  • Keycloak-based IAM service

e2e-tests/ — Playwright E2E Tests ⚠️ WORK IN PROGRESS​

  • Playwright + TypeScript test suite for the AMS frontend
  • Status: Infrastructure and test files are scaffolded but tests have NOT been run yet and are NOT verified to pass. Do NOT treat these tests as a source of truth or as passing CI.
  • Do NOT run npm test here as part of any task unless explicitly asked to work on e2e tests.
  • Mock mode (USE_MOCKS=true): intercepts GraphQL via page.route() — no backend needed
  • Live mode (USE_MOCKS=false): requires full stack (backend + Keycloak + frontend)
  • See e2e-tests/playwright.config.ts and e2e-tests/helpers/navigation.ts for structure

Shared Conventions​

  • Use GraphQL as primary API protocol (REST only where necessary)
  • Auth via Keycloak (OIDC/OAuth2) across all services
  • Teams are org-scoped (not workspace-scoped) — a team is assigned to workspaces via TeamWorkspaceAssignment
  • Effective role = member.roleOverride ?? team.baseRole (COALESCE pattern)
  • Clients are org-scoped directly (client.orgId) — no team membership, not workspace-scoped
  • Slugs are unique within their parent scope (workspace slug per user, team slug per workspace)

Architecture Reference — Read First for Any Non-Trivial Task​

Before implementing features or debugging, read:

  • Functional system architecture (diagrams, org structure, roles, invitation flows, navigation): docu/docs/domain/system-architecture.md
  • Technical architecture (ERD, permission evaluation, JPQL queries, system components, package structure): docu/docs/technical/architecture.md

Documentation — Domain Reference​

Before implementing features, read the Domain Reference for business rules, entity relationships, and system behaviour:

  • Data model & all entities: docu/docs/domain/data-model.md
  • Organizations & workspaces: docu/docs/domain/organizations-workspaces.md
  • Roles & permissions (cascading, data scoping): docu/docs/domain/roles-permissions.md
  • Permission matrices (configurable system & app permissions, default tables, UI): docu/docs/domain/permissions-matrix.md
  • Client profiles & sharing (PublicUserProfile): docu/docs/domain/client-profiles.md
  • Applications (entity, types, lifecycle): docu/docs/domain/applications.md
  • Applicants (types, roles, client vs applicant): docu/docs/domain/applicants.md
  • Application status & workflow (custom statuses, engine, history): docu/docs/domain/status-workflow.md
  • Document system (5 layers, snapshot rule, review flow): docu/docs/domain/document-system.md
  • Wizard steps (step types, custom forms, translations, split-panel editor): docu/docs/domain/wizard-steps.md
  • Comments & messaging (internal vs external, categories, action log): docu/docs/domain/comments-messaging.md
  • Notifications (flow, triggers, message format): docu/docs/domain/notifications.md
  • Subscription & Billing (org plans, personal plans, Stripe, lifecycle, superadmin platform): docu/docs/domain/subscription.md

Feature Guides​

  • See docu/docs/ai/claude/rules/frontend-build.md for build errors vs. warnings, what to ignore, known as any patterns, missing codegen types, and how to confirm the build is clean
  • See docu/docs/ai/claude/rules/notifications.md for the full notification system (bell icon, panel, persistence, message format, where to fire notifications)
  • See docu/docs/ai/claude/rules/core-application-status.md for the ApplicationStatus domain model, all renamed/deleted types from the TemplateStatus refactor, GraphQL field names, frontend hook names, and common pitfalls
  • See docu/docs/ai/claude/rules/permissions.md for the permission matrix system — entities, services, @PreAuthorize patterns, frontend hooks, how to add a new permission, and common pitfalls
  • See docu/docs/ai/claude/rules/system-translations.md for the System Translations feature — DB override pipeline, Zustand store, useTranslation hook, admin page, adding keys, common pitfalls
  • See docu/docs/ai/claude/rules/ai-assistant.md for the AI Assistant feature — OrgAIConfig entity, AIProvider abstraction, chat panel, Zustand store, context injection (AI Translate), seeding pitfalls, DB constraint fix
  • See docu/docs/ai/claude/rules/async-jobs.md for the Async Job system — background task infrastructure, AsyncJob entity, AsyncJobService lifecycle, @Async wiring pattern, useJobProgress hook, JobProgressDisplay component, common pitfalls
  • See docu/docs/ai/claude/rules/help-center.md for the Help Center AI chat page — HelpCenterChatService, platform-guide.txt maintenance, HELP_CENTER ChatMode, MarkdownMessage link resolver, session history filtering, common pitfalls
  • See docu/docs/ai/claude/rules/subscription.md for the Subscription & Billing system — org/personal plans, SubscriptionPlan entity, OrgSubscriptionService/UserSubscriptionService, Stripe webhook controller, SubscriptionLifecycleScheduler, <UpgradeDialog>, <PlanBadge>, superadmin admin pages, common pitfalls
  • Use /a-skill to create or update a skill — covers naming conventions, four-file pattern, templates, checklist, and rename instructions
  • See .claude/agents/workflow-statuses-feature.md for template statuses, status transitions matrix, ReactFlow workflow builder, application workflow display, WorkflowEngine, system handlers, and all known pitfalls
  • See .claude/agents/wizard-steps-feature.md for the wizard steps split-panel editor — step types, detail components, custom form schema + JSON editor, translation system, DnD reordering, layout pitfalls
  • See .claude/skills/a-ams-deploy/SKILL.md for the full deployment reference — ams-deploy repo layout, Portainer GitOps stacks (develop + production), GitFlow CI/CD pipeline, keycloak-config-cli realm import, all Portainer env vars, rollback procedure, and known pitfalls. Read this before touching any CI pipeline, docker-compose file, Portainer stack, or Keycloak realm config.

Skill Conventions​

All skills live in .claude/skills/ and must be named with the a- prefix (e.g. a-validate, a-ai-assistant-feature). This prefix distinguishes owner-created skills from built-in Claude Code commands.

There are two kinds of skills:

  • Action skills — a single SKILL.md with step-by-step instructions for a repeatable task (e.g. a-validate, a-codegen, a-commit)
  • Feature skills — four companion files that together document a system component end-to-end:
    1. docu/docs/domain/<feature>.md — user documentation
    2. docu/docs/ai/claude/rules/<feature>.md — technical/architecture reference for AI agents
    3. .claude/agents/a-<feature>.md — agent definition (loaded by the Agent tool)
    4. .claude/skills/a-<feature>/SKILL.md — skill entry point

To create or update a skill, use /a-skill. It contains the full template, checklist, and update/rename instructions.

Agents Available​

See .claude/agents/ for available agents:

  • complete-feature — full CRUD feature with listing + detail pages (frontend)
  • simple-table — listing-only table feature (frontend)
  • create-application-process — multi-step wizard form (frontend)
  • messages-feature — global/per-app Messages inbox (two-panel layout, comment threads, unread tracking, thread tree, sort/filter, sidenav badge)
  • workflow-statuses-feature — template statuses (custom status CRUD, transitions matrix), ReactFlow workflow builder, and application detail workflow display (read-only flow + history tab)
  • a-wizard-steps-feature — wizard steps split-panel editor: step types, custom form schema (JSON editor + live preview), translation system (per-locale, auto-derived keys), DnD reordering, detail components for all step types
  • a-ai-assistant-feature — AI Config settings, global chat panel, AI Translate for wizard steps, Zustand store, context injection, provider abstraction (Claude + OpenAI)
  • a-async-jobs-feature — async job infrastructure: AsyncJob entity, AsyncJobService lifecycle, @Async wiring, useJobProgress hook, JobProgressDisplay component; add new job types here
  • a-help-center-feature — Help Center AI chat page: HelpCenterChatService, platform-guide.txt maintenance, HELP_CENTER ChatMode, MarkdownMessage link resolver, session history filtering by chatMode
  • a-subscription-billing-feature — Subscription & Billing system: org plans, personal plans, Stripe integration, SubscriptionLifecycleScheduler, <UpgradeDialog> feature gating, <PlanBadge>, org/personal billing pages, Axvero Platform superadmin pages (dashboard, plans editor, org management, email templates, schedules, Stripe config)

Git Commit Convention​

  • Do NOT add Co-Authored-By lines to commit messages
  • Keep commit messages concise and descriptive
  • Format: short summary line, then bullet points if needed