Skip to content

docs: comprehensive developer environment documentation for self-service onboarding #935

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JemimahEkong wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: comprehensive developer environment documentation for self-service onboarding #935

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
117682b
feat: optimize Bull background job processing
JemimahEkong Jun 26, 2026
49fd279
docs: comprehensive developer environment documentation
JemimahEkong Jun 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
279 changes: 157 additions & 122 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,60 +1,154 @@
## 🚦 Local Validation: Analytics & Cost Tracking
# TeachLink Backend

To quickly validate feature analytics and cost tracking end-to-end:
[![CI](https://github.com/teachlink/backend/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/teachlink/backend/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-70%25%20threshold-brightgreen)](#-ci--testing)
[![Branch Protection](https://img.shields.io/badge/branch%20protection-enabled-blue)](#-branch-protection)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](CONTRIBUTING.md)

```bash
# 1. Install dependencies
npm install
> **Replace** `teachlink/backend` in the badge URLs above with your actual `org/repo` slug once the repository is on GitHub.

# 2. Start backend (in background)
npm run start:dev &
**TeachLink** is a decentralized platform for sharing, analyzing, and monetizing knowledge. This is the **NestJS backend API** — the core service powering the TeachLink ecosystem.

# 3. Start infra monitoring stack
cd infra/monitoring
cp -n .env.example .env || true
docker compose up -d
cd ../../
---

# 4. Send test analytics event
curl -X POST http://localhost:3000/analytics/event \
-H 'Content-Type: application/json' \
-d '{"category":"feature","action":"launch_button_clicked"}'
## Quick Start (5 minutes)

# 5. Send test cost event
curl -X POST http://localhost:3000/metrics/cost \
-H 'Content-Type: application/json' \
-d '{"amountUsd": 5}'
```bash
# 1. Clone and install
git clone https://github.com/teachlink/backend.git
cd teachlink_backend
pnpm install

# 6. Open Prometheus: http://localhost:9090 and search for feature_events_total and infrastructure_hourly_cost_usd
# 7. Open Grafana: http://localhost:3001 (admin/admin) and view the TeachLink Overview dashboard
```
# 2. Configure environment
cp .env.example .env
# (edit .env with your settings, defaults work for local dev)

Or run the helper script:
# 3. Start databases
docker compose up -d postgres redis

```bash
./setup-local.sh
# 4. Start the server
pnpm start:dev

# 5. Verify it works
curl http://localhost:3000/health
```

To stop the backend:
Open http://localhost:3000/api/docs for the interactive API documentation.

> **New developer?** See the full [setup guide](docs/setup.md) for detailed instructions, prerequisites, and troubleshooting.

---

## Prerequisites

| Tool | Version | Install |
|------|---------|---------|
| Node.js | >= 18 | [nodejs.org](https://nodejs.org/) |
| pnpm | >= 8 | `npm install -g pnpm` |
| Docker | >= 24 | [docker.com](https://www.docker.com/products/docker-desktop/) |
| Docker Compose | >= 2.24 | Included with Docker Desktop |
| Git | >= 2 | [git-scm.com](https://git-scm.com/) |

---

## Onboarding Documentation

| Document | Description |
|----------|-------------|
| [Setup guide](docs/setup.md) | Step-by-step setup from scratch |
| [Troubleshooting guide](docs/troubleshooting.md) | Common issues and fixes |
| [Developer runbook](docs/runbook.md) | Day-to-day operational commands |
| [Migrations guide](docs/migrations.md) | Database migration commands |
| [API documentation](http://localhost:3000/api/docs) | Swagger UI (requires running server) |

---

## Setup Video Tutorial

A video walkthrough for visual learners. Covers installation, configuration, and first API call.

**Video link:** https://example.com/setup-video *(placeholder — to be recorded)*

**What the video covers:**

1. Installing prerequisites (Node.js, pnpm, Docker)
2. Cloning the repo and installing dependencies
3. Environment variable configuration explained
4. Starting PostgreSQL and Redis with Docker
5. Running database migrations
6. Starting the development server
7. Making your first API request
8. Running the verification script

---

## Available Commands

| Command | Description |
|---------|-------------|
| `pnpm start:dev` | Start dev server with hot-reload |
| `pnpm build` | Compile TypeScript to `dist/` |
| `pnpm lint` | Lint and auto-fix |
| `pnpm typecheck` | TypeScript type checking |
| `pnpm test` | Run unit tests |
| `pnpm test:e2e` | Run end-to-end tests |
| `pnpm validate:env` | Validate environment variables |
| `pnpm migrate:run` | Run pending migrations |
| `pnpm migrate:status` | Check migration status |
| `pnpm verify` | Run setup verification |

---

## CI / Testing

Every pull request and every push to `main` / `develop` runs an automated pipeline defined in [`.github/workflows/ci.yml`](.github/workflows/ci.yml).

### Pipeline stages

| Stage | Tool | Fails on |
| -------------- | ---------------- | ----------------------------------------- |
| **Install** | `pnpm install` | Dependency resolution error |
| **Lint** | ESLint | Any warning or error (`--max-warnings 0`) |
| **Format** | Prettier | Any file that would be reformatted |
| **Type Check** | `tsc --noEmit` | Any TypeScript error |
| **Build** | NestJS CLI | Compilation failure |
| **Unit Tests** | Jest + ts-jest | Test failure or coverage below 70 % |
| **E2E Tests** | Jest + Supertest | Test failure (uses real Postgres + Redis) |

### Running checks locally

```bash
kill $(lsof -ti:3000)
```
# Lint (auto-fix)
pnpm lint

# 🧠 TeachLink Backend
# Lint (CI-strict, no auto-fix)
pnpm lint:ci

[![CI](https://github.com/teachlink/backend/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/teachlink/backend/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-70%25%20threshold-brightgreen)](#-ci--testing)
[![Branch Protection](https://img.shields.io/badge/branch%20protection-enabled-blue)](#-branch-protection)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](CONTRIBUTING.md)
# Format check (no rewrite)
pnpm format:check

> **Replace** `teachlink/backend` in the badge URLs above with your actual `org/repo` slug once the repository is on GitHub.
# TypeScript type check only
pnpm typecheck

**TeachLink** is a decentralized platform built to enable technocrats to **share, analyze, and monetize knowledge, skills, and ideas**. This repository contains the **backend API** built with **NestJS**, **TypeORM**, and powered by **Starknet** and **PostgreSQL**, serving as the core of the TeachLink ecosystem.
# Unit tests with coverage report
pnpm test:ci

This is the **NestJS** backend powering TeachLink — offering APIs, authentication, user management, notifications, and knowledge monetization features.
# E2E tests (requires Postgres + Redis running locally)
pnpm test:e2e
```

- Pagination is limited to a maximum page size of **100** items per request.
### Coverage thresholds

Configured in `jest.config.js`. The pipeline fails if **any** global metric falls below:

| Metric | Threshold |
| ---------- | --------- |
| Statements | 70 % |
| Branches | 70 % |
| Functions | 70 % |
| Lines | 70 % |

Coverage HTML report is uploaded as a GitHub Actions artifact (`coverage-report`) on every run.

---

Expand Down Expand Up @@ -442,107 +536,48 @@ When replicas are configured, TypeORM replication routes writes to the primary a

See [docs/database-read-replicas.md](docs/database-read-replicas.md) for setup, routing behavior, consistent-read guidance, and failover operations.

## �🚀 Getting Started

### Prerequisites

- **Node.js** 18+ with npm
- **PostgreSQL** 14+ (or Docker)
- **Redis** 6+ (for caching and queues)
- **Git** for version control

### Quick Start

1. **Clone the repository**

```bash
git clone https://github.com/teachlink/backend.git
cd teachlink_backend
```
## Getting Started

2. **Install dependencies**

```bash
npm install
```
Detailed setup instructions are available in the [setup guide](docs/setup.md).

3. **Set up environment variables**
**Quick reference:**

```bash
cp .env.example .env
# Edit .env with your configuration
pnpm install # Install dependencies
cp .env.example .env # Configure environment
docker compose up -d postgres redis # Start databases
pnpm start:dev # Start dev server
pnpm verify # Verify setup
```

4. **Start PostgreSQL and Redis**

```bash
# Using Docker (recommended)
docker-compose up -d postgres redis
### Access the API

# Or install locally and start services
# PostgreSQL: sudo systemctl start postgresql
# Redis: sudo systemctl start redis
```
| Endpoint | URL |
|----------|-----|
| REST API | http://localhost:3000 |
| API Documentation | http://localhost:3000/api/docs |
| Health Check | http://localhost:3000/health |

5. **Run database migrations**

```bash
npm run typeorm migration:run
```
### Docker Compose

6. **Start the development server**
A development `docker-compose.yml` is provided at the project root:

```bash
npm run start:dev
```

7. **Access the API**

- **REST API**: http://localhost:3000
- **API Documentation**: http://localhost:3000/api
- **Health Check**: http://localhost:3000/health

### Environment Configuration

Key environment variables to configure:

```env
# Database
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=postgres
DATABASE_PASSWORD=yourpassword
DATABASE_NAME=teachlink

# Authentication
JWT_SECRET=your-super-secret-jwt-key
ENCRYPTION_SECRET=your-32-char-encryption-key

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# External Services (Optional)
STRIPE_SECRET_KEY=your_stripe_key
AWS_ACCESS_KEY_ID=your_aws_key
AWS_SECRET_ACCESS_KEY=your_aws_secret
```

### Docker Setup

For complete development environment with Docker:
# Start all infrastructure services
docker compose up -d

```bash
# Start all services
docker-compose up -d
# Start only database services (for local dev)
docker compose up -d postgres redis

# View logs
docker-compose logs -f
docker compose logs -f

# Stop services
docker-compose down
# Stop everything
docker compose down
```

For the full monitoring stack (Prometheus, Grafana, Elasticsearch, Kibana), see `infra/monitoring/docker-compose.yml`.

## 🤝 Contributing

We welcome contributions from the community! Please follow our guidelines to ensure a smooth contribution process.
Expand Down
Loading
Loading