Contributing

Architecture overview

Before writing any code, read the how it works page. It explains how the three services fit together and how data flows through the system.

Repository overview

Nous is open-source and the code is at github.com/NousC/opennous. It’s a pnpm monorepo with three apps:

App	What it is
`apps/api`	Express API — all REST routes, OAuth, enrichment
`apps/worker`	Background worker — pollers (Gmail, Calendar, SMTP, Slack) + inbound webhook handlers
`apps/frontend`	React + Vite SPA

Plus packages/core — shared DB helpers, contact resolution, and type definitions used by both api and worker. The main scripts are:

pnpm dev          # start all apps in development mode
pnpm typecheck    # TypeScript check across all apps
pnpm lint         # lint all apps
pnpm test         # run all tests

API

Express.js with ESM throughout. Routes live in apps/api/src/routes/ split into:

/api/* — internal app routes (Supabase JWT auth)
/v1/* — REST API routes (API key auth)
/inbound/* — unauthenticated webhook receivers (routed via Caddy to the worker)

Worker

Node.js service that runs pollers on a schedule (Gmail every 30min, Calendar every 10min, SMTP every 15min, Slack hourly) and handles inbound webhooks from Instantly, Fireflies, Fathom, Calendly, and LinkedIn/Unipile.

Frontend

React + Vite + TailwindCSS + shadcn/ui. No Next.js — pure SPA served by nginx in production.

Database

Supabase (Postgres). Schema is in supabase/schema.sql. No ORM — raw Supabase client queries.

Development setup

Clone and install

git clone https://github.com/NousC/opennous.git
cd nous
pnpm install

Configure environment

cp nous.env.example nous.env

At minimum you need:

SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY — from your Supabase project → Settings → API
VITE_SUPABASE_URL + VITE_SUPABASE_ANON_KEY — same project, anon key
ANTHROPIC_API_KEY — for AI features
ENCRYPTION_KEY — random 32-byte hex string (openssl rand -hex 32)

Run the schema

In your Supabase SQL editor, run the contents of supabase/schema.sql.

Start development

pnpm dev

This starts the API on :3000, worker on :3001, and frontend on :5173.

Before submitting a PR

Under 3 lines — submit directly.
Over 3 lines — open an issue or discuss in Discord first. This avoids wasted effort if the approach doesn’t fit the direction.

PR process

Fork the repo and create a feature branch from main
Make your changes
Run pnpm typecheck and pnpm lint — fix any errors
Submit a PR with a clear description of what and why
Link any related issues

Code conventions

ESM throughout — no CommonJS require()
Named exports only — no default exports
No hardcoded secrets or API keys
No AI-generated PRs

Commit style

feat: add stakeholder map to get_contact response
fix: identity resolution waterfall missing email-prefix fallback
docs: add MCP tool examples for record_observation

Types: feat · fix · docs · refactor · test · chore

Get help

Discord

Fastest way to get help — chat, screenshots, screen sharing.

GitHub Issues

For bug reports and feature requests.

​Architecture overview

​Repository overview

​API

​Worker

​Frontend

​Database

​Development setup

​Before submitting a PR

​PR process

​Code conventions

​Commit style

​Get help