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:
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:
- Confirm the file exists in
apps/api/app.
- Read the route handler for its auth expectations.
- Check nearby tests or OpenAPI artifacts when present.
- Verify request and response examples against the implementation.
- 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.
Docs link check fails
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.