API Overview

Client → Gateway (auth · tenant · rate-limit · throttle · logging · audit) → Surface Router

GET https://api.leadmetrics.io/dashboard/v1/campaigns

Authorization: Bearer <JWT>

interface LeadmetricsJWT {
  sub:        string;   // user.ref_id
  tenantId:   string;   // tenant.ref_id (absent for super_admin cross-tenant tokens)
  role:       'admin' | 'member' | 'reviewer' | 'super_admin';
  appAccess:  ('dashboard' | 'dm-portal' | 'manage')[];
  iat:        number;
  exp:        number;   // 15 min for access tokens, 7 days for refresh tokens
}

GET /dashboard/v1/campaigns/01ARZ3NDEKTSV4RRFFQ69G5FAV

// Query parameters (all optional)
interface PaginationQuery {
  limit?:  number;   // default 25, max 100
  cursor?: string;   // ULID of the last item from the previous page
  order?:  'asc' | 'desc';  // default 'desc' (newest first)
}
 
// Response envelope
interface PaginatedResponse<T> {
  data:       T[];
  pagination: {
    hasMore:    boolean;
    nextCursor: string | null;  // pass as cursor on next request
    total?:     number;         // included when count is cheap; omitted otherwise
  };
}

GET /dashboard/v1/activities?filter.status=in_progress&filter.agentRole=copywriter
GET /dm/v1/approvals?filter.riskLevel=high&filter.tenantId=01ARZ...

interface ApiError {
  error: {
    code:    string;    // machine-readable, e.g. 'NOT_FOUND', 'VALIDATION_ERROR'
    message: string;    // human-readable description
    field?:  string;    // for VALIDATION_ERROR — which field failed
    details?: unknown;  // additional structured context (optional)
  };
}

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1704067261

event: text_delta
data: {"delta":"Here is the","activityId":"01ARZ..."}

event: activity_completed
data: {"activityId":"01ARZ...","status":"done","outputRef":"mongo:..."}

event: approval_created
data: {"approvalId":"01ARZ...","type":"content_review","riskLevel":"high"}

apps/api/src/
├── app.ts                 # Fastify app setup — plugins, routers, error handler
├── index.ts               # Bootstrap — starts server, Redis plugin, worker
├── lib/
│   ├── auth.ts            # requireTenantUser, apiError, bearerToken helpers
│   ├── jwt.ts             # JWT sign/verify (returns null, never throws)
│   └── logger.ts          # Shared pino instance (LOG_LEVEL env)
├── services/              # Pure business logic, no Fastify deps
│   ├── auth.service.ts         # Registration helpers, invoice number generation
│   ├── billing.service.ts      # Invoice amounts, line items, billing dates
│   ├── blog.service.ts         # Blog post approval/rejection state machine
│   ├── social.service.ts       # Social post approval/rejection state machine
│   ├── campaign.service.ts     # Campaign import + create helpers
│   ├── campaigns.service.ts    # Google Ads token + service helpers
│   ├── channels.service.ts     # Channel metric aggregators, date utils
│   ├── channel-connect.service.ts  # OAuth helpers, callback URL builders
│   ├── tenants.service.ts      # Tenant invoice + social post RAG helpers
│   ├── strategy.service.ts     # Strategy pipeline helpers
│   ├── landing-page.service.ts # Landing page helpers
│   ├── lead.service.ts         # Lead helpers
│   ├── connected-channel.service.ts
│   ├── baseline-sync.service.ts
│   └── zoho-books-sync.ts      # Zoho Books API integration
├── routers/
│   ├── auth.ts            # /auth/v1 — login, refresh, logout, me, plans, register
│   ├── admin.ts           # /admin/v1 — tenants, users, agents, billing, skills, templates, audit
│   ├── tenant.ts          # /tenant/v1 — agents, billing, context, strategy, notifications, chat
│   ├── media.ts           # /media/v1 — image search (Pixabay/Unsplash), pick, assets
│   ├── docs.ts            # /tenant/v1/docs — document upload, list, delete (RAG)
│   ├── knowledge.ts       # /tenant/v1/knowledge — knowledge base queries
│   └── rag-config.ts      # /admin/v1/rag-config — Qdrant / embedding config
├── schemas/               # OpenAPI schema objects for Swagger docs
│   ├── shared.ts          # Bearer auth, error responses, common fragments
│   ├── tenant.schema.ts   # Schemas for /tenant/v1 routes
│   ├── docs.schema.ts     # Schemas for /tenant/v1/docs routes
│   └── media.schema.ts    # Schemas for /media/v1 routes
├── socket/
│   └── index.ts           # Socket.IO — notifications, presence, agent events (4 Redis connections)
├── worker.ts              # BullMQ worker — processes agent jobs
└── __tests__/
    ├── setup.ts           # Test DB config, env var stubs
    ├── helpers.ts         # cleanDb(), createTenant(), createUser()
    ├── jwt.test.ts        # Unit tests for lib/jwt.ts
    ├── lib-auth.test.ts   # Unit tests for lib/auth.ts
    ├── media-router.test.ts
    └── integration/
        ├── admin-users.test.ts
        ├── auth-profile.test.ts    # GET/PATCH /auth/v1/me, password change, plans, refresh, logout
        ├── docs.test.ts
        ├── knowledge.test.ts
        ├── notifications.test.ts
        ├── rag-config.test.ts
        ├── register.test.ts
        ├── security.test.ts
        ├── tenant-notification-prefs.test.ts
        └── tenant-pipeline.test.ts