Skip to main content
This guide is for engineers and internal integrators working on the Winnerr monorepo. It reflects the current repository behavior: the CRM web app, API app, provider webhooks, workflows, and MCP integration surfaces.
Winnerr’s public third-party REST API and official language SDKs are not documented as launched surfaces in this repository. Do not build against /v1 examples, package names, sandbox hosts, or developer-dashboard flows unless a supported integration contract has been provided separately.

Prerequisites

  • Node.js 18 or newer.
  • pnpm 8 or newer.
  • Access to the required environment variables for the app, API, database, auth provider, and any provider integrations you are testing.
  • PostgreSQL-compatible database access for local development.

Install dependencies

From the repository root:

Configure environment

Create local environment files for the apps you are running. At minimum, local app/API development expects these URL values to agree:
Add provider-specific keys only for the features you are actively developing or testing, such as Twilio, Nylas, AI services, storage, observability, or MCP OAuth clients. Never commit real secrets.

Start local services

Use the root scripts for the common workflows:
Default local URLs:

Work with API routes

Most product API routes live in apps/api/app/api, and provider webhook routes live in apps/api/app/webhooks. API routes are not guaranteed to share a global response envelope, pagination model, or public /v1 path. Before documenting or consuming a route:
  1. Confirm the file exists in apps/api/app.
  2. Read the route handler for its auth expectations.
  3. Check nearby tests or OpenAPI artifacts when present.
  4. Verify request and response examples against the implementation.
  5. Keep route files thin: auth and request parsing in the route, shared behavior in packages.

Authentication patterns

Web app to API app

When the web app calls the separate API app, forward the session token as a bearer token:
In apps/api routes, read that bearer token with getAuthFromRequest(request) and scope data access to the returned orgId.

MCP OAuth

The OAuth endpoints in apps/api/app/oauth support MCP-style OAuth 2.1 with PKCE. They are not a replacement for a general public developer portal.

Verify your changes

Run the checks that match the area you changed:

Troubleshooting

API requests return 401 locally

  • Confirm NEXT_PUBLIC_API_URL points at http://localhost:3002 in the web app.
  • Confirm the frontend forwards Authorization: Bearer <token>.
  • Confirm the API route uses getAuthFromRequest(request) instead of same-server auth() when it is called from apps/app.

Webhooks do not fire locally

  • Confirm the provider webhook URL points to your reachable API app URL.
  • Confirm provider signature validation is configured for the environment you are testing.
  • Confirm the route returns the provider-specific response shape, such as TwiML for Twilio flows.
Run pnpm --dir apps/docs lint and fix links to pages that exist in apps/docs/mint.json or the docs filesystem. Use relative docs paths such as /communication/phone or /development rather than stale template links.