Skip to content

Commit 7577510

Browse files
RUKAYAT-CODERRUKAYAT-CODER
authored
Merge pull request #935 from JemimahEkong/docs/dev-environment-setup
docs: comprehensive developer environment documentation for self-service onboarding
2 parents 51d8565 + ae18387 commit 7577510

25 files changed

Lines changed: 2449 additions & 238 deletions

‎README.md‎

Lines changed: 158 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,157 @@
1+
# TeachLink Backend
2+
3+
[![CI](https://github.com/teachlink/backend/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/teachlink/backend/actions/workflows/ci.yml)
4+
[![Coverage](https://img.shields.io/badge/coverage-70%25%20threshold-brightgreen)](#-ci--testing)
5+
[![Branch Protection](https://img.shields.io/badge/branch%20protection-enabled-blue)](#-branch-protection)
6+
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](CONTRIBUTING.md)
17
## 🚦 Local Validation: Analytics & Cost Tracking
28
q
39
To quickly validate feature analytics and cost tracking end-to-end:
410

5-
```bash
6-
# 1. Install dependencies
7-
npm install
11+
> **Replace** `teachlink/backend` in the badge URLs above with your actual `org/repo` slug once the repository is on GitHub.
812
9-
# 2. Start backend (in background)
10-
npm run start:dev &
13+
**TeachLink** is a decentralized platform for sharing, analyzing, and monetizing knowledge. This is the **NestJS backend API** — the core service powering the TeachLink ecosystem.
1114

12-
# 3. Start infra monitoring stack
13-
cd infra/monitoring
14-
cp -n .env.example .env || true
15-
docker compose up -d
16-
cd ../../
15+
---
1716

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

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

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

32-
Or run the helper script:
29+
# 3. Start databases
30+
docker compose up -d postgres redis
3331

34-
```bash
35-
./setup-local.sh
32+
# 4. Start the server
33+
pnpm start:dev
34+
35+
# 5. Verify it works
36+
curl http://localhost:3000/health
3637
```
3738

38-
To stop the backend:
39+
Open http://localhost:3000/api/docs for the interactive API documentation.
40+
41+
> **New developer?** See the full [setup guide](docs/setup.md) for detailed instructions, prerequisites, and troubleshooting.
42+
43+
---
44+
45+
## Prerequisites
46+
47+
| Tool | Version | Install |
48+
|------|---------|---------|
49+
| Node.js | >= 18 | [nodejs.org](https://nodejs.org/) |
50+
| pnpm | >= 8 | `npm install -g pnpm` |
51+
| Docker | >= 24 | [docker.com](https://www.docker.com/products/docker-desktop/) |
52+
| Docker Compose | >= 2.24 | Included with Docker Desktop |
53+
| Git | >= 2 | [git-scm.com](https://git-scm.com/) |
54+
55+
---
56+
57+
## Onboarding Documentation
58+
59+
| Document | Description |
60+
|----------|-------------|
61+
| [Setup guide](docs/setup.md) | Step-by-step setup from scratch |
62+
| [Troubleshooting guide](docs/troubleshooting.md) | Common issues and fixes |
63+
| [Developer runbook](docs/runbook.md) | Day-to-day operational commands |
64+
| [Migrations guide](docs/migrations.md) | Database migration commands |
65+
| [API documentation](http://localhost:3000/api/docs) | Swagger UI (requires running server) |
66+
67+
---
68+
69+
## Setup Video Tutorial
70+
71+
A video walkthrough for visual learners. Covers installation, configuration, and first API call.
72+
73+
**Video link:** https://example.com/setup-video *(placeholder — to be recorded)*
74+
75+
**What the video covers:**
76+
77+
1. Installing prerequisites (Node.js, pnpm, Docker)
78+
2. Cloning the repo and installing dependencies
79+
3. Environment variable configuration explained
80+
4. Starting PostgreSQL and Redis with Docker
81+
5. Running database migrations
82+
6. Starting the development server
83+
7. Making your first API request
84+
8. Running the verification script
85+
86+
---
87+
88+
## Available Commands
89+
90+
| Command | Description |
91+
|---------|-------------|
92+
| `pnpm start:dev` | Start dev server with hot-reload |
93+
| `pnpm build` | Compile TypeScript to `dist/` |
94+
| `pnpm lint` | Lint and auto-fix |
95+
| `pnpm typecheck` | TypeScript type checking |
96+
| `pnpm test` | Run unit tests |
97+
| `pnpm test:e2e` | Run end-to-end tests |
98+
| `pnpm validate:env` | Validate environment variables |
99+
| `pnpm migrate:run` | Run pending migrations |
100+
| `pnpm migrate:status` | Check migration status |
101+
| `pnpm verify` | Run setup verification |
102+
103+
---
104+
105+
## CI / Testing
106+
107+
Every pull request and every push to `main` / `develop` runs an automated pipeline defined in [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
108+
109+
### Pipeline stages
110+
111+
| Stage | Tool | Fails on |
112+
| -------------- | ---------------- | ----------------------------------------- |
113+
| **Install** | `pnpm install` | Dependency resolution error |
114+
| **Lint** | ESLint | Any warning or error (`--max-warnings 0`) |
115+
| **Format** | Prettier | Any file that would be reformatted |
116+
| **Type Check** | `tsc --noEmit` | Any TypeScript error |
117+
| **Build** | NestJS CLI | Compilation failure |
118+
| **Unit Tests** | Jest + ts-jest | Test failure or coverage below 70 % |
119+
| **E2E Tests** | Jest + Supertest | Test failure (uses real Postgres + Redis) |
120+
121+
### Running checks locally
39122

40123
```bash
41-
kill $(lsof -ti:3000)
42-
```
124+
# Lint (auto-fix)
125+
pnpm lint
43126

44-
# 🧠 TeachLink Backend
127+
# Lint (CI-strict, no auto-fix)
128+
pnpm lint:ci
45129

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

51-
> **Replace** `teachlink/backend` in the badge URLs above with your actual `org/repo` slug once the repository is on GitHub.
133+
# TypeScript type check only
134+
pnpm typecheck
135+
136+
# Unit tests with coverage report
137+
pnpm test:ci
138+
139+
# E2E tests (requires Postgres + Redis running locally)
140+
pnpm test:e2e
141+
```
142+
143+
### Coverage thresholds
52144

53-
**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.
145+
Configured in `jest.config.js`. The pipeline fails if **any** global metric falls below:
54146

55-
This is the **NestJS** backend powering TeachLink — offering APIs, authentication, user management, notifications, and knowledge monetization features.
147+
| Metric | Threshold |
148+
| ---------- | --------- |
149+
| Statements | 70 % |
150+
| Branches | 70 % |
151+
| Functions | 70 % |
152+
| Lines | 70 % |
56153

57-
- Pagination is limited to a maximum page size of **100** items per request.
154+
Coverage HTML report is uploaded as a GitHub Actions artifact (`coverage-report`) on every run.
58155

59156
---
60157

@@ -442,107 +539,48 @@ When replicas are configured, TypeORM replication routes writes to the primary a
442539

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

445-
## �🚀 Getting Started
446-
447-
### Prerequisites
448-
449-
- **Node.js** 18+ with npm
450-
- **PostgreSQL** 14+ (or Docker)
451-
- **Redis** 6+ (for caching and queues)
452-
- **Git** for version control
542+
## Getting Started
453543

454-
### Quick Start
544+
Detailed setup instructions are available in the [setup guide](docs/setup.md).
455545

456-
1. **Clone the repository**
546+
**Quick reference:**
457547

458548
```bash
459-
git clone https://github.com/teachlink/backend.git
460-
cd teachlink_backend
549+
pnpm install # Install dependencies
550+
cp .env.example .env # Configure environment
551+
docker compose up -d postgres redis # Start databases
552+
pnpm start:dev # Start dev server
553+
pnpm verify # Verify setup
461554
```
462555

463-
2. **Install dependencies**
556+
### Access the API
464557

465-
```bash
466-
npm install
467-
```
468-
469-
3. **Set up environment variables**
470-
471-
```bash
472-
cp .env.example .env
473-
# Edit .env with your configuration
474-
```
475-
476-
4. **Start PostgreSQL and Redis**
558+
| Endpoint | URL |
559+
|----------|-----|
560+
| REST API | http://localhost:3000 |
561+
| API Documentation | http://localhost:3000/api/docs |
562+
| Health Check | http://localhost:3000/health |
477563

478-
```bash
479-
# Using Docker (recommended)
480-
docker-compose up -d postgres redis
481-
482-
# Or install locally and start services
483-
# PostgreSQL: sudo systemctl start postgresql
484-
# Redis: sudo systemctl start redis
485-
```
486-
487-
5. **Run database migrations**
488-
489-
```bash
490-
npm run typeorm migration:run
491-
```
564+
### Docker Compose
492565

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

495568
```bash
496-
npm run start:dev
497-
```
498-
499-
7. **Access the API**
500-
501-
- **REST API**: http://localhost:3000
502-
- **API Documentation**: http://localhost:3000/api
503-
- **Health Check**: http://localhost:3000/health
504-
505-
### Environment Configuration
506-
507-
Key environment variables to configure:
508-
509-
```env
510-
# Database
511-
DATABASE_HOST=localhost
512-
DATABASE_PORT=5432
513-
DATABASE_USER=postgres
514-
DATABASE_PASSWORD=yourpassword
515-
DATABASE_NAME=teachlink
516-
517-
# Authentication
518-
JWT_SECRET=your-super-secret-jwt-key
519-
ENCRYPTION_SECRET=your-32-char-encryption-key
520-
521-
# Redis
522-
REDIS_HOST=localhost
523-
REDIS_PORT=6379
524-
525-
# External Services (Optional)
526-
STRIPE_SECRET_KEY=your_stripe_key
527-
AWS_ACCESS_KEY_ID=your_aws_key
528-
AWS_SECRET_ACCESS_KEY=your_aws_secret
529-
```
530-
531-
### Docker Setup
532-
533-
For complete development environment with Docker:
569+
# Start all infrastructure services
570+
docker compose up -d
534571

535-
```bash
536-
# Start all services
537-
docker-compose up -d
572+
# Start only database services (for local dev)
573+
docker compose up -d postgres redis
538574

539575
# View logs
540-
docker-compose logs -f
576+
docker compose logs -f
541577

542-
# Stop services
543-
docker-compose down
578+
# Stop everything
579+
docker compose down
544580
```
545581

582+
For the full monitoring stack (Prometheus, Grafana, Elasticsearch, Kibana), see `infra/monitoring/docker-compose.yml`.
583+
546584
## 🤝 Contributing
547585

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

0 commit comments

Comments
 (0)