> ## Documentation Index
> Fetch the complete documentation index at: https://docs.projectzoe.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Server Setup

> Full developer setup guide for the Project Zoe NestJS API server.

## Prerequisites

| Requirement | Version |
| ----------- | ------- |
| Node.js     | 18+     |
| PostgreSQL  | 14+     |
| Redis       | 6+      |

***

## Clone and install

```bash theme={null}
git clone https://github.com/kanzucodefoundation/project-zoe-server.git
cd project-zoe-server
git checkout develop
npm install
```

***

## Environment configuration

```bash theme={null}
cp .env.sample .env
```

Key variables:

| 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

```bash theme={null}
createdb projectzoe-db
```

***

## Start the server

```bash theme={null}
npm run start:dev
```

The server runs at **[http://localhost:4002](http://localhost:4002)** with hot-reload enabled.

<Tip>
  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.
</Tip>

***

## Seed demo data

```bash theme={null}
# 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
```

To reset seeded data:

```bash theme={null}
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
```