Prerequisites
| Requirement | Version |
|---|---|
| Node.js | 18+ |
| PostgreSQL | 14+ |
| Redis | 6+ |
Clone and install
git clone https://github.com/kanzucodefoundation/project-zoe-server.git
cd project-zoe-server
git checkout develop
npm install
Environment configuration
cp .env.sample .env
| Variable | Description | Default |
|---|---|---|
DB_HOST | Postgres host | localhost |
DB_PORT | Postgres port | 5432 |
DB_USERNAME | Postgres user | — |
DB_PASSWORD | Postgres password | — |
DB_DATABASE | Database name | projectzoe-db |
DB_SYNCHRONIZE | Auto-sync schema (local only) | true |
APP_ENVIRONMENT | local / staging / production | local |
JWT_SECRET | Secret for signing access tokens | — |
JWT_REFRESH_SECRET | Secret for refresh tokens | — |
JWT_EXPIRY | Access token TTL (e.g. 15m) | 15m |
JWT_REFRESH_EXPIRY | Refresh token TTL (e.g. 7d) | 7d |
REDIS_HOST | Redis host | localhost |
REDIS_PORT | Redis port | 6379 |
REDIS_PASSWORD | Redis password (leave blank for local) | — |
PORT | Server port | 4002 |
SENTRY_DSN | Sentry error tracking URL (optional) | — |
Create the database
createdb projectzoe-db
Start the server
npm run start:dev
In
local mode, TypeORM auto-syncs the schema on startup via DB_SYNCHRONIZE=true. You do not need to run migrations locally during normal development.Seed demo data
# Create the demo tenant and an admin user
npm run command create-tenant demo
# Seed 7 users, 68 groups, 50+ contacts, 4 report types, and 500+ submissions
npm run seed:comprehensive
npm run seed:reset # clear + re-seed
npm run seed:clear # clear only
Available scripts
| Script | Description |
|---|---|
npm run start:dev | Start with hot-reload |
npm run start:prod | Run compiled output |
npm run build | Compile TypeScript |
npm test | Run unit tests |
npm run test:e2e | Run end-to-end tests |
npm run lint | Lint the codebase |
npm run format | Format with Prettier |
npm run migration:generate -- src/migrations/<Name> | Generate migration from entity changes |
npm run migration:run | Apply pending migrations |
npm run migration:revert | Roll back last migration |
npm run migration:show | List applied/pending migrations |
npm run seed:comprehensive | Seed demo data |
npm run seed:reset | Clear + re-seed |
npm run seed:clear | Clear seeded data |
Swagger / API docs
The NestJS Swagger module is enabled in non-production environments. Once the server is running, visit:http://localhost:4002/api/docs
Project structure
src/
├── app.module.ts # Root module — imports all feature modules
├── main.ts # Entry point
├── config.ts # Database config, entity list
├── auth/ # JWT auth, guards, decorators
├── users/ # Users, roles, permissions
├── tenants/ # Tenant management
├── crm/ # Contacts, relationships, requests
├── groups/ # Group tree, memberships
├── events/ # Events, attendance, registration
├── attendance/ # Service & fellowship schedules
├── finance/ # Accounts, transactions, reconciliation
├── reports/ # Report templates, submissions
├── tasks/ # Task management
├── notifications/ # WebSocket gateway, push notifications
├── dashboard/ # Aggregated stats
├── search/ # Global search
├── shared/ # Base entities, tenant context, repositories
├── seed/ # Demo data seeding
└── utils/ # Helpers, logging, validation