Magic Core

Magic Core is the TypeScript backend behind Magic Resume: a pnpm-workspace monorepo split by runtime profile into independently deployable NestJS apps. The two business services share one Postgres database via Prisma.

platform-api (port 3111) — light BFF / CRUD: users, resumes, collaboration, notifications, stats, analytics, webhooks, auth. No Chromium.
agent-service (port 3112) — heavy AI: DeepAgents-driven chat / workflows / interview, a realtime interview WebSocket, PDF parse, translation, TTS. Resume PDF export is generated client-side by the frontend.
gateway (port 3110) — edge entry point that verifies identity and routes /api/* traffic to platform-api or agent-service.

Three internal packages back them:

@magic/db — Prisma schema, generated client, and PrismaService (the single DB entry point).
@magic/shared — cross-cutting infrastructure: auth guard, Redis, health checks, domain event bus, domain exceptions, request context, the response envelope, and logging.
@magic/testing — test helpers (buildTestApp, mock Prisma/Redis/Config, Testcontainers fixtures), devDependency only.

There is no published npm package to install. “The SDK” here is the HTTP + SSE API surface of these services. You integrate by issuing authenticated HTTP requests — from a browser, a Node script, a backend, or any language with an HTTP client.

System at a glance

In production a single nginx entry point forwards traffic to gateway, which routes by /api path prefix.


                         ┌──────────────────────────┐
   client / SDK  ───────▶│  nginx  (single base URL) │
   Authorization: Bearer └────────────┬─────────────┘
                                      │
                                      ▼
                           ┌──────────────────────┐
                           │       gateway        │
                           │       :3110          │
                           └──────────┬───────────┘
                                      │ path-prefix routing
                  ┌───────────────────┴────────────────────┐
                  ▼                                         ▼
        ┌───────────────────┐                   ┌──────────────────────┐
        │    platform-api    │  shared Postgres  │     agent-service    │
        │    :3111  (CRUD)   │◀───── + Redis ───▶│     :3112 (AI/SSE)   │
        └───────────────────┘                   └──────────────────────┘

In local development there’s no nginx — each service listens on its own port (3110 / 3111 / 3112); point your client at gateway or whichever service owns the route.

Tech stack

Runtime: Node 22 (also runs on 20), pnpm 9 workspace, node-linker=hoisted (flat node_modules).
Framework: NestJS 11, global prefix /api, Swagger UI at /api/docs on each service.
Data: PostgreSQL + Prisma (migrations run only by platform-api), Redis (rate limiting / cache / sessions).
AI: DeepAgents engine — a LangGraph loop over an OpenAI-compatible model (@langchain/openai), streamed as SSE.
PDF export: generated client-side by the frontend; Core keeps PDF parsing only.
Auth: Clerk session JWT + Personal Access Token (mr_pat_…).

Start here

Architecture & conventions Prerequisites Configuration Local development Authentication (PAT)First calls

Before you integrate

Every successful platform-api response is wrapped in an envelope: { code, data, message, timestamp } — your real payload is in data. See Response envelope.
Agent-service endpoints stream results as Server-Sent Events (text/event-stream), one JSON object per data: line, each tagged with a type. See SSE events.
Auth: use a Personal Access Token (mr_pat_…) or a Clerk session JWT. See Authentication.