Skip to main content

README.md

Imported Content​

Anchor MSP PSA

AgentField-first PSA platform for MSP operations, built for multi-environment GitOps delivery.

Repo layout​

  • apps/web: Next.js operator console and client portal.
  • apps/gateway: API gateway for authn/authz, idempotency, and orchestration.
  • apps/agentfield-mock: Local mock control-plane for end-to-end testing.
  • apps/status-mock: Mock status API + telemetry control-center endpoints.
  • packages/contracts: Shared API contracts, events, and OpenAPI spec.
  • packages/ui: Shared UI components and design tokens.
  • agents/*: Domain agents and edge telemetry agent.
  • infra/*: Source deployment manifests mirrored into the dedicated ops repo (anchor-msp-ops).
  • docs/*: Architecture, runbooks, and compliance guidance.

Quick start​

cp .env.example .env
pnpm install
pnpm dev

Optional local data services:

docker compose -f infra/docker-compose.dev.yaml up -d

Final Testing Flow​

  1. Start full local stack (infra + gateway + workers + mock AgentField + web):
pnpm dev:stack
  1. In another terminal, run smoke tests:
pnpm test:smoke
  1. Inspect mock status/telemetry events:
curl -s http://localhost:8090/v1/events
curl -s http://localhost:8090/api/telemetry/events

Apply SQL migrations in order:

  1. infra/sql/0001_init.sql
  2. infra/sql/0002_psa_resources.sql
  3. infra/sql/0003_idempotency.sql
  4. infra/sql/0004_event_pipeline.sql
  5. infra/sql/0005_job_queue.sql
  6. infra/sql/0006_security_hardening.sql
  7. infra/sql/0007_configuration_plane.sql
  8. infra/sql/0008_job_metadata.sql
  9. infra/sql/0009_workflow_execution_metadata.sql
  10. infra/sql/0010_worker_runtime.sql
  11. infra/sql/0011_portal_invites.sql

Or run:

DATABASE_URL=postgres://anchor:anchor@localhost:5432/anchor ./scripts/apply-migrations.sh

Run outbox dispatcher:

pnpm --filter @anchor/gateway worker:outbox

Generate a dev JWT when AUTH_MODE=jwt:

JWT_SIGNING_SECRET=dev-jwt-secret node scripts/generate-dev-jwt.mjs

Production/staging required secrets and keys:

  • JWT_SIGNING_SECRET (>= 32 chars)
  • AUDIT_SIGNING_SECRET (>= 32 chars)
  • RESOURCE_ENCRYPTION_KEY_B64 (base64-encoded 32-byte key)
  • AGENTFIELD_WEBHOOK_SECRET
  • DATABASE_URL
  • PORTAL_BASE_URL (required in staging/prod; invite link host)
  • ANCHOR_OPERATOR_JWT (web server-to-server JWT for dashboard API calls)

Optional local seed data:

DATABASE_URL=postgres://anchor:anchor@localhost:5432/anchor ./scripts/seed-dev-data.sh

Key endpoints​

  • GET /health
  • GET /api/v1/health
  • GET /.well-known/engine-status
  • GET /api/v1/openapi
  • POST /api/v1/events/ingest
  • GET /api/v1/edge-agent/policy
  • POST /api/v1/execute/{agent}.{reasoner}
  • GET /api/v1/workflow-executions
  • GET /api/v1/workflow-executions/{id}
  • POST /api/v1/workflow-executions/{id}/retry
  • POST /api/v1/workflow-executions/{id}/cancel
  • GET /api/v1/portal/knowledge-base
  • GET /api/v1/portal/invites
  • POST /api/v1/portal/invites
  • POST /api/v1/portal/invites/{id}/revoke
  • POST /api/v1/portal/tickets
  • POST /api/v1/ops/alerts/{id}/link-ticket
  • POST /api/v1/ops/tickets/{id}/resolve
  • GET /api/v1/agent-runtime/health
  • POST /api/v1/agent-runtime/smoke
  • POST /api/v1/agent-runtime/outbox-failures/{id}/retry
  • POST /api/v1/agent-runtime/job-failures/{id}/retry
  • POST /api/v1/integrations/github/webhook
  • POST /api/v1/integrations/accounting/sync
  • POST /api/v1/imports
  • GET /api/v1/jobs
  • GET /api/v1/platform/settings
  • PUT /api/v1/platform/settings
  • GET /api/v1/workspace/settings
  • PUT /api/v1/workspace/settings

UI configuration console:

  • GET /admin/settings (web control plane for runtime settings and encrypted secret refs)
  • GET / (full inventory + universal CRUD for all PSA resources)
  • GET /ops (runtime failures, retries, workflow control, smoke execution)
  • GET /portal (ticket/approval/invoice workflows + KB + payment visibility)

Delivery model​

  • Workspace-per-client tenancy
  • App/ops split: this repo builds artifacts; anchor-msp-ops is the GitOps deployment source.
  • Kubernetes + Argo CD promotion path (dev -> staging -> prod)
  • GitHub Actions CI/CD with signed artifacts and SBOM generation hooks

Core docs​

  • docs/architecture.md
  • docs/api.md
  • docs/auth.md
  • docs/agentfield.md
  • docs/agents.md
  • docs/database.md
  • docs/testing.md
  • docs/telemetry.md
  • docs/gitops.md
  • docs/compliance.md