Stellar Uzima Backend

A robust, scalable NestJS backend for the Stellar Uzima health and wellness platform. This repository contains the core API and services that power the Uzima ecosystem.

📋 Table of Contents

• Overview
• Tech Stack
• Project Structure
• Getting Started
• Development
• API Documentation
• Contributing
• License

🎯 Overview

Stellar Uzima is a comprehensive health and wellness platform designed to help users manage their health goals, track progress, and receive personalized recommendations. The backend provides:

• Authentication & Authorization: Secure user authentication with JWT tokens
• User Management: Complete user profile and account management
• Health Tasks: Track and manage health-related tasks and habits
• Data Persistence: Robust database operations with TypeORM
• Error Handling: Comprehensive error handling and logging
• API Documentation: Auto-generated API documentation with Swagger

🛠 Tech Stack

• Runtime: Node.js (v18+)
• Framework: NestJS 10+
• Language: TypeScript
• Database: PostgreSQL with TypeORM
• Authentication: JWT (JSON Web Tokens)
• Validation: class-validator, class-transformer
• Testing: Jest
• API Documentation: Swagger/OpenAPI
• Linting & Formatting: ESLint, Prettier

🎨 Code Quality & Formatting

This project uses ESLint for code linting and Prettier for automatic code formatting to ensure consistent code style across all contributions.

Available Scripts

Run these commands to maintain code quality:

# Run linting and automatically fix issues
npm run lint

# Only check for linting issues without fixing
npm run lint:check

# Run Prettier to format all files
npm run format

# Only check if files are properly formatted
npm run format:check

# Run both linting fixes and formatting
npm run lint:format

Configuration Files

• .eslintrc.js: ESLint configuration with TypeScript support
• .prettierrc: Prettier formatting rules
• .prettierignore: Files to exclude from formatting
• eslint.config.mjs: Modern ESLint flat configuration

Pre-commit Checks

A pre-commit hook automatically runs linting and formatting checks before code is committed to ensure only properly formatted code enters the repository.

📁 Project Structure

backend/
├── src/
│   ├── main.ts                 # Application entry point
│   ├── app.module.ts           # Root module
│   ├── app.controller.ts       # Root controller
│   ├── app.service.ts          # Root service
│   │
│   ├── common/                 # Shared utilities and components
│   │   ├── decorators/         # Custom decorators (auth, roles, etc.)
│   │   ├── filters/            # Exception filters
│   │   ├── guards/             # Authentication & authorization guards
│   │   ├── interceptors/       # Request/response interceptors
│   │   ├── pipes/              # Validation and transformation pipes
│   │   ├── dtos/               # Common DTOs (pagination, responses)
│   │   └── utils/              # Utility functions and helpers
│   │
│   ├── config/                 # Configuration management
│   │   ├── database.config.ts
│   │   ├── app.config.ts
│   │   └── validation.schema.ts
│   │
│   ├── database/               # Database setup and migrations
│   │   ├── migrations/
│   │   ├── seeds/
│   │   └── entities/           # Database entities
│   │
│   ├── modules/                # Feature modules
│   │   ├── auth/               # Authentication module
│   │   │   ├── auth.module.ts
│   │   │   ├── auth.controller.ts
│   │   │   ├── auth.service.ts
│   │   │   ├── strategies/     # Passport strategies
│   │   │   ├── guards/
│   │   │   └── dtos/
│   │   │
│   │   ├── users/              # User management module
│   │   │   ├── users.module.ts
│   │   │   ├── users.controller.ts
│   │   │   ├── users.service.ts
│   │   │   ├── entities/
│   │   │   └── dtos/
│   │   │
│   │   └── health-tasks/       # Health tasks module
│   │       ├── health-tasks.module.ts
│   │       ├── health-tasks.controller.ts
│   │       ├── health-tasks.service.ts
│   │       ├── entities/
│   │       └── dtos/
│   │
│   └── shared/                 # Shared services (mail, notifications, etc.)
│       ├── mail/
│       ├── notifications/
│       └── logger/
│
├── test/                       # End-to-end tests
│   └── app.e2e.spec.ts
│
├── package.json
├── tsconfig.json
├── nest-cli.json
├── jest.config.js
├── .env.example
├── .eslintrc.js
├── .prettierrc
├── .gitignore
├── Dockerfile
├── docker-compose.yml
└── README.md

🚀 Getting Started

Prerequisites

• Node.js >= 18.x
• npm, yarn, or pnpm
• PostgreSQL 12+

Installation

1. Clone the repository

   git clone https://github.com/Stellar-Uzima/Uzima-Backend.git
   cd backend

2. Install dependencies

   npm install
   # or
   yarn install
   # or
   pnpm install

3. Setup environment variables

   cp .env.example .env
   # Edit .env with your configuration

4. Run database migrations

   npm run migrate

5. Seed the database (optional)

   npm run seed
   # or
   npm run seed:db

6. Start the development server

   npm run start:dev

The application will be available at http://localhost:3000

💻 Development

Available Scripts

# Development
npm run start          # Start the application
npm run start:dev     # Start with hot reload
npm run start:debug   # Start with debug mode

# Building
npm run build         # Build for production
npm run build:watch  # Build with watch mode

# Testing
npm run test          # Run unit tests
npm run test:watch   # Run tests with watch mode
npm run test:cov     # Run tests with coverage
npm run test:e2e     # Run e2e tests

# Database
npm run migrate       # Run migrations
npm run migrate:revert # Revert last migration
npm run seed         # Seed the database
npm run seed:db      # Run database seeders

# Linting & Formatting
npm run lint         # Run ESLint
npm run lint:fix    # Fix linting errors
npm run format      # Format with Prettier

Code Style

This project uses ESLint and Prettier for code consistency:

• ESLint: Enforces code quality rules
• Prettier: Handles automatic code formatting

# Format all files
npm run format

# Check and fix linting issues
npm run lint:fix

Environment Variables

See .env.example for all available environment variables:

# App
NODE_ENV=development
PORT=3000
API_PREFIX=api

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=password
DB_DATABASE=uzima_dev

# JWT
JWT_SECRET=your-secret-key
JWT_EXPIRATION=7d

# CORS
CORS_ORIGIN=http://localhost:3000

# Mail (optional)
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USER=your-email@example.com
MAIL_PASSWORD=your-password

📚 API Documentation

API documentation is available via Swagger at:

http://localhost:3000/api/docs

To regenerate OpenAPI documentation:

npm run swagger

🧪 Testing

The project uses Jest for unit and integration testing.

Running Tests

# Run all tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:cov

Writing Tests

Create test files next to the modules with .spec.ts suffix:

// Example: users.service.spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { UsersService } from './users.service';

describe('UsersService', () => {
  let service: UsersService;

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [UsersService],
    }).compile();

    service = module.get<UsersService>(UsersService);
  });

  it('should be defined', () => {
    expect(service).toBeDefined();
  });
});

🔄 API Versioning

This API uses URI-based versioning. All endpoints are available under /api/v1/.

Current Version

Version	Status	Base URL
v1	Active	/api/v1/

Examples

GET /api/v1/auth/login GET /api/v1/users/profile

Versioning Strategy

When breaking changes are introduced, a new version (e.g., /api/v2/) will be added. Existing versions remain available to allow gradual client migration.

🐳 Docker

Local development with Docker Compose

Start PostgreSQL and Redis (recommended for local development):

docker compose up -d postgres redis

Wait until both services are healthy:

docker compose ps

Copy environment variables and ensure Redis/DB point at Docker:

cp .env.example .env
# DB_HOST=localhost, DB_PORT=5432, REDIS_URL=redis://localhost:6379

Run migrations and start the API on your machine:

npm install
npm run migrate
npm run start:dev

The API runs at http://localhost:3001 (see APP_PORT in .env).

Optional: run the full stack in Docker

docker compose --profile full up -d

Build Docker image only

docker build -t uzima-backend .

Useful commands

docker compose logs -f postgres redis   # follow service logs
docker compose down                   # stop services
docker compose down -v                # stop and remove volumes

📖 Module Guides

Detailed documentation for each module is available in their respective README files:

• Auth Module - Authentication and authorization
• Users Module - User management
• Health Tasks Module - Health task tracking
• Database Module - Database setup and migrations

📦 Dependency updates

This repository uses Dependabot (see .github/dependabot.yml):

• Weekly pull requests for routine npm dependency updates (non-breaking, reviewed before merge).
• Daily monitoring with prioritized PRs for security patches (labeled security).
• Maintainers should merge security updates promptly; routine updates can follow the normal PR review process.

🤝 Contributing

We welcome contributions! Please read our CONTRIBUTOR_GUIDE.md for detailed guidelines on:

• Setting up your development environment
• Making code changes
• Creating pull requests
• Code review process
• Commit message conventions

📝 Commit Convention

We follow conventional commits:

feat: Add new feature
fix: Fix a bug
docs: Update documentation
style: Code style changes
refactor: Refactor code
perf: Performance improvements
test: Add or update tests
chore: Maintenance tasks

🔒 Security

• Never commit .env files with sensitive data
• Always use environment variables for secrets
• Validate all user inputs
• Follow OWASP security guidelines
• Report security issues to the maintainers

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For issues, questions, or suggestions:

1. Check existing GitHub Issues
2. Create a new issue with a clear description
3. Contact the maintainers

🚀 Deployment

For production deployment guidelines, see DEPLOYMENT.md

---

Happy coding! 🎉