Developer Documentation

Technical documentation for developers working on the Postmill codebase. This directory covers architecture, conventions, and infrastructure — everything you need to contribute effectively.

Target audience: Developers contributing to the Postmill monorepo (NestJS backend + Inngest job handler, Next.js frontend, shared libraries, Prisma).

---

API surfaces at a glance

Surface	Base path	Description
Public API v1	/public/v1	REST API for integrations, posts, media, and the full analytics surface (/public/v1/analytics/*) — used by the dashboard, n8n, Zapier, and the SDK.
MCP Server	MCP protocol	AI agent tools exposed via Model Context Protocol.

---

Stability commitments

• Schema — prisma migrate deploy is the migration method. Additive changes (nullable columns, defaulted columns) are safe. Renames and drops require an expand-contract plan.
• AI provider resolution — no env-var fallback. Per-tenant configuration through AIOrgProviderConfig.
• Provider framework — the kernel is the sole resolution path; there are no parallel registries or kill switches.

---

Page index

Page	Description
Local Development	Get the stack running locally with minimal resources: Docker profiles, feature flags, memory guidance.
Architecture	High-level monorepo architecture, app/library layout, data flow.
AI Architecture	Pluggable multi-provider AI layer: AIModelProvider, categories, surfaces, adapters, governance services.
Database	Prisma schema management, migrate-deploy workflow, repository-only access, encryption at rest.
Data Model	Prisma models grouped by domain with keys and relationships.
Backend Conventions	NestJS layering (Controller → Service → Repository), DTO validation, CSRF, security invariants.
Frontend Conventions	Next.js App Router structure, SWR data fetching, Tailwind 3 styling, capability-aware UI.
Provider Framework	Kernel, identity triple, versions, catalog/health APIs.
Provider Versions	Live provider catalog grouped by domain.
Integrations	The channel-integration model: IntegrationManager, credential resolution, capability matrix, per-channel VPN egress.
Public API v1	Public REST API endpoints for third-party integrations and automation.
Analytics API	Unified multi-channel analytics API under /public/v1/analytics/* with snapshot-based data.
MCP	Model Context Protocol server entrypoints, auth, rate limiting.
OAuth Apps	OAuth application registration and management.
Plugs	Automation hooks (auto plugs and post plugs) for social channel providers.
SDK	Official @postmill-ai/postmill-sdk Node.js SDK for the Public API.
Webhooks	Webhook configuration, dispatch, and SSRF-safe delivery.
Adding a Provider	Step-by-step guide for adding a new social channel provider.
Adding an AI Adapter	Guide for implementing a new AI provider adapter.
Adding a Media Studio	Descriptor + adapter + route recipe for the studio-kit.
Testing	Vitest per-package configuration, co-located specs, CI workflow.
Setup Gate	The /setup onboarding wizard and gate semantics.
Contributing	Ground rules, invariants, PR workflow, review checklist.
Glossary	Terminology used across the codebase.

---

Related docs

Page	Location	Description
AI Tools (user guide)	../user-guide/ai-tools.md	End-user view of AI features.
Supported Channels	../user-guide/supported-channels.md	User-facing capability matrix for social channels.
Operations Guide	../operations-guide/	Self-hosting, deployment, monitoring.

---

Repository layout (quick reference)

apps/
  backend/         NestJS REST API — thin controllers + module wiring + Inngest handler
  frontend/        Next.js (App Router) + React — port 4200
  extension/       Browser extension
  commands/        CLI commands
  sdk/             Published SDK

libraries/
  nestjs-libraries/    Core backend logic, Prisma schema, repositories
  helpers/             Shared utilities, useFetch hook
  react-shared-libraries/  Shared React components
  providers/           Provider kernel + per-provider packages

tools/               Repo-owned tooling (not a workspace)
  db/                Migration/backfill helpers + the CI schema gates
  codegen/           Generators whose output is committed and drift-gated

docker/              Dockerfiles, dev compose files, nginx.conf, entrypoints
e2e/                 Playwright suite + seed data

Dockerfile           Pinned at the root: the image CI publishes
docker-compose.yaml  Pinned at the root: the self-hoster quick-start
openapi.yml          Generated from the controllers — never hand-edited

Root scripts/ is maintainer-local and gitignored; a fresh clone does not have it. Anything CI or a documented workflow needs lives in tools/.

Verified against v1.0.0