A modern, scalable backend API for real estate transactions built with NestJS and PostgreSQL

• User Management - Registration, authentication, and profile management
• Property Listings - Create, manage, and search property listings
• Transaction Tracking - Record and track real estate transactions
• Tax Strategy Suggestions - Store informational, non-binding tax structuring suggestions for transactions
• Document Management - Store and manage property-related documents
• Role-Based Access Control - USER, AGENT, ADMIN roles with route protection
• Clean Architecture - Modular, testable, and maintainable code structure
• CI/CD Ready - Automated testing and deployment pipeline

The application implements comprehensive RBAC with three user roles:

• USER: Default role for registered users. Can create properties and manage their own data.
• AGENT: Can manage properties and assist with transactions.
• ADMIN: Full system access including user management, property administration, and system configuration.

Routes are protected using decorators:

@UseGuards(JwtAuthGuard, RolesGuard)
@Roles(UserRole.ADMIN)
@Get('admin/users')
getAllUsers() {
  // Only admins can access
}

New users are automatically assigned the USER role upon registration.

The application provides secure password reset functionality via email:

1. Request Reset: User submits email address
2. Token Generation: Secure reset token created (expires in 1 hour)
3. Email Delivery: Reset link sent to user's email
4. Token Validation: Token verified on password reset
5. Password Update: New password hashed and stored

# Request password reset
POST /auth/password-reset/request
{
  "email": "[email protected]"
}

# Reset password with token
POST /auth/password-reset/reset
{
  "token": "reset-token-here",
  "newPassword": "NewSecurePassword123!"
}

• Token Expiration: Reset tokens expire after 1 hour
• Single Use: Tokens can only be used once
• Password History: Prevents reuse of recent passwords
• Rate Limiting: Previous tokens invalidated on new request
• Blocked User Protection: No emails sent to blocked accounts

• Node.js >= 18.0.0
• PostgreSQL >= 14
• npm >= 8.0.0

# Install dependencies
npm install

# Copy environment file
cp .env.example .env

# Set up your database URL in .env file

A production Dockerfile is included and docker-compose.yml wires up the full stack (app, postgres, pgbouncer, redis).

# Build and boot the full stack
docker compose up --build

# Verify container health (GET /healthz returns 200)
curl -fsSL http://localhost:3000/healthz

# Tear down (including volumes)
docker compose down -v

• The app container applies pending Prisma migrations (prisma migrate deploy) via docker-entrypoint.sh before starting node dist/main.
• Health checks: postgres/pgbouncer/redis use their native probes; the app service probes GET /healthz.
• Override secrets via .env variables: POSTGRES_PASSWORD, JWT_SECRET, JWT_REFRESH_SECRET, REDIS_PASSWORD. The JWT secrets must each be at least 32 characters or the app will refuse to boot.

The application uses environment variables for configuration. Copy .env.example to .env and adjust the values as needed.

# Generate Prisma Client
npm run db:generate

# Run migrations
npm run migrate

# (Optional) Seed database
npm run db:seed

# Development mode
npm run start:dev

# Production mode
npm run build
npm run start:prod

# Unit tests
npm test

# Test coverage
npm run test:cov

# Watch mode
npm run test:watch

For database-backed integration tests, set TEST_DATABASE_URL to a dedicated test database. Helper utilities are available in test/database/prisma-test-helpers.ts to clean fixtures and reset seeded state between suites.

src/
├── database/           # Database configuration and Prisma service
├── users/              # User management module
├── properties/         # Property listings module
├── app.module.ts       # Main application module
├── app.controller.ts   # App controller with health check
└── main.ts             # Application entry point

prisma/
├── schema.prisma       # Database schema
└── seed.ts             # Database seeding

• User - Platform users (buyers, sellers, agents, admins)
• Property - Real estate listings with detailed information
• Transaction - Property transactions with blockchain integration
• Document - Property-related documents and files

• Properties module: src/properties/README.md
• Transactions module: src/transactions/README.md
• Auth & Users: docs/Auth_and_User_APIs.md

Create a .env file based on .env.example:

DATABASE_URL=postgresql://user:password@localhost:5432/propchain
PORT=3000
JWT_SECRET=your-secret-key

The CI/CD pipeline is configured in .github/workflows/ci.yml:

• Develop branch → Deploys to staging
• Main branch → Deploys to production

# Build for production
npm run build

# Run migrations
npm run migrate:deploy

# Start application
npm run start:prod

• GET /api/health - Application health status

• POST /api/users - Create user
• GET /api/users - List all users
• GET /api/users/:id - Get user by ID
• PUT /api/users/:id - Update user
• DELETE /api/users/:id - Delete user

• POST /api/properties - Create property
• GET /api/properties - List all properties
• GET /api/properties/:id - Get property by ID
• PUT /api/properties/:id - Update property
• DELETE /api/properties/:id - Delete property

• GET /api/transactions/:transactionId/tax-strategies - List tax strategy suggestions for a transaction
• POST /api/transactions/:transactionId/tax-strategies - Create a tax strategy suggestion
• PATCH /api/transactions/:transactionId/tax-strategies/:strategyId - Update a tax strategy suggestion

Tax strategy suggestions are informational only and are not legal or tax advice. See docs/Tax_Strategy_Suggestions.md for usage details.

See CONTRIBUTING.md for contribution guidelines, branch naming conventions, PR expectations, and local test/lint instructions.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License.

For support, email [email protected] or join our Slack channel

• TypeScript strict mode: The project now enables strict TypeScript checks. The base config is in tsconfig.json.
• Key compiler flags enforced: noImplicitAny, strictNullChecks and related strict checks are enabled for app builds via tsconfig.app.json.
• ESLint rules: @typescript-eslint/no-explicit-any is set to error and explicit boundary/return types are encouraged via @typescript-eslint/explicit-module-boundary-types and @typescript-eslint/explicit-function-return-type (set to warn). See .eslintrc.js.

Local checks before committing/pushing:

# Install
npm ci

# Run linter (auto-fixable issues)
npm run lint

# Build to verify TypeScript strict checks
npm run build

CI: A GitHub Actions workflow (.github/workflows/ci.yml) now runs npm run lint and npm run build on pushes and PRs to main to validate the stricter compilation and linting rules.