AI Agent Guide

Platform AI Guide

Welcome, Agent. Platform is an extensible, multi-tenant SaaS foundation built on Elixir, Ash Framework, and SvelteKit. It ships with a comprehensive Helpdesk, Analytics pipeline, and enterprise-grade Authentication as its core modules, and is architecturally designed to extend into any business domain — commerce, CRM, HR, ERP, or beyond.

🏗 Project Architecture

Component	Path	OTP App	Primary Namespace	Role
Domain (Core)	packages/core	:platform_core	Platform.*	Ash Resources, Domains, and Business Logic.
Domain (Helpdesk)	packages/helpdesk	:platform_helpdesk	Platform.Helpdesk.*	Conversations, messages, and SLA management (Agent role).
Domain (Notifications)	packages/notifications	:platform_notifications	Platform.Notifications.*	Multi-channel notification delivery (in-app, email, SMS).
Domain (Analytics)	packages/analytics	:platform_analytics	Platform.Analytics.*	Broadway ingestion pipeline, PageView + BusinessEvent.
API	apps/api	:platform_api	Platform.API.*	Phoenix Interface, AshJsonApi, GraphQL, Typescript RPC.
Web	apps/web	N/A	SvelteKit	Main User Interface (Frontend).
Docs	apps/docs	N/A	Astro	Public Documentation site.
Docs Internal	packages/docs-internal	N/A	Astro	Internal Documentation site.

🏗 Project Overview

The core modules are Helpdesk (tickets, conversations, SLA), Analytics (Broadway ingestion, dashboards), and Authentication (enterprise-grade multi-tenant auth). The package architecture is domain-isolated so new modules (commerce, CRM, HR, etc.) can be added without touching existing packages.

• Backend (apps/api): Elixir, Phoenix, and Ash Framework — resource-oriented API with JSON API, GraphQL, and custom RPC surfaces.
• Frontend (apps/web): SvelteKit + Svelte 5 + Tailwind CSS 4.
• Documentation (apps/docs): Astro/Starlight documentation site.
• Infrastructure: Docker Compose for local Postgres + Uptrace (OpenTelemetry).

🔑 Key Technologies

Backend (Elixir/Phoenix/Ash)

• Ash Framework: Central to the domain logic. Defines resources, actions, and policies.
• Ash Authentication: Handles user identity and session management.
• Ash Admin: Provides a generated administrative interface for managing resources.
• API Interfaces: Supports JSON API (ash_json_api), GraphQL (ash_graphql), and custom RPC.
• Database: PostgreSQL (via ash_postgres).

Frontend (SvelteKit)

• Svelte 5: Utilizing runes ($state, $derived, etc.) for modern reactivity.
• Tailwind CSS 4: For styling with utility classes.
• OpenTelemetry: Integrated for frontend tracing.

Tooling & Workspace

• Mise: Used for managing tool versions (elixir, node, bun, biome) and running project-wide tasks. Key tasks: mise run dev-api (Phoenix on :4000), mise run dev-web (SvelteKit on :5173), mise run infra up (Docker: Postgres + Uptrace).
• Bun: The primary JavaScript package manager and workspace runner.
• Biome: Used for linting and formatting JavaScript/TypeScript/JSON files.

Testing Instructions

• In elixir it is advised to go into the directory of the package where the test is located then run mix test test/file.exs
• For typescript use bun vitest run src/file.test.ts use the run command so it does not invoke watch mode

🛡 Guardrails & Standards

All development must adhere to the platform’s guardrails. These are the primary sources of truth for mandatory and prohibited practices.

• ALWAYS DO: Master Index — Mandatory practices.

  • Ash API
  • Backend & Data Integrity
  • Frontend
  • Testing
  • Shared Standards

• NEVER DO: Master Index — Prohibited practices.

  • Ash API
  • Backend & Data Integrity
  • Frontend
  • Testing
  • Shared Standards

• Core Review Checklist — Used by workspace-mason:review for automated and manual code reviews.

📏 Development Conventions

Code Style

• JavaScript/TypeScript/JSON: Follows Biome defaults (linting + formatting). Format on save is recommended.
• Svelte / Markdown / YAML: Uses Prettier — Biome intentionally excludes these file types.
• Elixir: Uses mix format (with the Styler plugin — output differs from vanilla formatter). Use mix credo for static analysis.
• Commits: Use conventional commits (e.g., feat: ..., fix: ...). Enforced via commitlint.

Backend (Phoenix)

• Resource definitions are located in packages/core/lib/platform/.
• Domain logic should be encapsulated within Ash resources and actions.
• You are able to use usage_rules where in apps/api you can run:

# Search all project dependencies
mix usage_rules.search_docs "search term"

# Search specific packages
mix usage_rules.search_docs "search term" -p ecto -p ash

For any related elixir questions, there are dedicated skills for ash and phoenix (accessible via /api-ash or /api-phoenix) which will help you solve specific problems regarding them.

Frontend (Svelte)

• Use Svelte 5 runes for reactivity.
• Components are located in apps/web/src/lib/ or packages/ui-svelte. This is exclusive for SvelteKit frontends; do not use it in the backend.
• The Svelte MCP server is available for documentation and code fixing.

🤖 AI Assistant Instructions

• Svelte Development: Always use the svelte-autofixer tool when writing Svelte code. Consult list-sections and get-documentation for Svelte 5/SvelteKit specifics.
• Ash/Phoenix: Use the api-ash and api-phoenix skills for specialized guidance on the backend.
• Feature Flags: Use getFeatureFlags() in the frontend to gate module-specific UI. See Domain Model for details.
• Context: Refer to AGENTS.md CLAUDE.md for additional AI-specific instructions and tool usage.

Feature Planning & Implementation

For any non-trivial feature, module, or domain work, use the platform-architect skill suite.

Full autopilot (design → plan → implement → review in one shot):

/workspace-mason <feature description>

Step-by-step (review between phases):

/workspace-mason:design <feature description>   # Director: produces design doc
/workspace-mason:plan <slug>                    # Director: produces plan + handoff
/workspace-mason:implement <slug>               # Implementor: worktree + TDD
/workspace-mason:review <slug>                  # Director: code review vs design
/workspace-mason:finalize <slug>                # Post-merge: apply doc updates to main

Other commands:

/workspace-mason:resume <slug>    # Resume interrupted implementation
/workspace-mason:status <slug>    # Check progress without making changes

Amending an existing feature (never edits original docs — creates amendment docs):

/workspace-mason:design "add bulk import amends:hr-leave-requests"

Examples:

• /workspace-mason:plan a HR module with employees and leave requests
• /workspace-mason:design add email campaign tracking to Marketing
• /workspace-mason:status hr-leave-requests

---

Note: This document is intended to be symlinked to the root AGENTS.md and CLAUDE.md to provide a unified entry point.