Documentation

AppEngine overview

What AppEngine is, the modules it ships, and how a request travels through the stack.

AppEngine is the AppMint backend — a NestJS service that exposes every domain (auth, storefront, CRM, banking, automation, AI) over REST and WebSockets. One deployment, one binary, one set of conventions. You point your frontends at it and pick the modules you need.

How a request flows

Every authenticated request hits the same pipeline before reaching a controller method.

  1. 1

    Middleware

    UsageMiddleware runs globally and meters the call against the org's plan and pricing tiers. Rate limiting plugs in here.

  2. 2

    JwtAuthGuard

    Registered as APP_GUARD in app.module.ts. It reads Authorization: Bearer <jwt> (or the x-api-key header) and resolves the principal — a User or a Customer. Routes decorated @PublicRoute() skip this guard.

  3. 3

    Roles & Permissions guards

    If a controller method has @Roles(RoleType.ConfigAdmin) or @RequirePermissions('update'), additional guards check the principal's roles and the collection's required-role policy.

  4. 4

    Controller method

    The method receives the request, the resolved principal, and the orgid header. It calls into a service, which talks to the repository layer.

  5. 5

    Repository

    RepositoryService mediates every collection read and write. It enforces tenant isolation (orgid), wraps payloads in BaseModel\<T\>, fires lifecycle events, and dispatches to a configured provider — MongoDB, Redis, S3, or a remote AWS replica.

Module map

AppEngine is split into focused modules. Each one owns its controllers, services, and repository hooks.

  • Users — sign-in, sign-up, OAuth, API keys, 2FA, devices, RBAC. Mounted at /profile/*, /user/*, /api-key/*.
  • Repositories — generic CRUD over every collection. Mounted at /repository/*.
  • Storefront — products, cart, checkout, orders, gift cards, returns, subscriptions. Mounted at /storefront/*.
  • CRM — contacts, leads, marketing, audiences, tickets, reservations, inbox. Mounted at /crm/*.
  • Chat / Voice / Phone — real-time messaging (WebSocket gateways), voice via OpenAI Realtime, phone-number management.
  • Broadcast — multi-channel messaging (email, SMS, WhatsApp, push) at /broadcast/*.
  • Banking — accounts, transfers, cards, KYC/KYB, lending, merchant checkout at /banking/*.
  • Automation — workflow + IVR engine at /automation/*.
  • AI — agent framework, streaming, function calling at /ai/*.
  • Sync — background jobs, social-network polling, queues. Mostly internal.
  • Upstream / Connect — vendor integrations (Stripe, Twilio, Google, SendGrid, etc.) at /upstream/* and /connect/*.
  • Site — CMS pages, dev environments, K8s deployments at /site/*.
  • Org Management — tenant config, billing, team members at /org-management/*.
  • Monitoring — health checks at /monitoring/health.

There are more — see the section sidebar for everything covered, or hit the Discovery API (/discover) for a live list.

What's the same everywhere

Once you understand a few cross-cutting rules, every module reads like a variation on the same pattern.

  • Every record is wrapped in BaseModel\<T\>. The payload lives at data; system fields live on the wrapper.
  • Every authenticated call sends an orgid header. Cross-tenant access is impossible unless the principal is a RootAdmin.
  • Every domain event flows through NestJS EventEmitter2. Workflows, sync jobs, and notifications subscribe via @OnEvent.
  • Every collection — built-in or custom — uses the same CRUD surface under /repository/*.

There is no first-class webhook module. External integrations (Stripe, SendGrid, Twilio, social platforms) post into domain-specific endpoints, and AppEngine fans out via the internal event bus. See Events and async.

Where to look next

If you're integrating from a frontend, start with Authentication. If you're modeling data, read BaseModel and Collections and schemas. The rest of this section covers the patterns you'll meet in every module.