Skip to content

README.md

Latest commit

 

History

History
172 lines (125 loc) · 5.41 KB

README.md

File metadata and controls

172 lines (125 loc) · 5.41 KB

Colabs Backend API

Node.js + TypeScript REST API for the SpaceYaTech open-source collaboration & freelance platform.

Tech Stack

Layer Technology
Runtime Node.js 20+
Framework Express.js + TypeScript
Database PostgreSQL 16 (Prisma ORM)
Cache Redis 7
Auth GitHub OAuth 2.0 + JWT
File Storage MinIO
Validation Zod
Testing Vitest

Prerequisites

  • Node.js 20+
  • Docker & Docker Compose

Local Setup

1. Clone & install

git clone https://github.com/SpaceyaTech/colabs-backend.git
cd colabs-backend
npm install

2. Configure environment

cp .env.example .env

Open .env and fill in these values — everything else has working defaults:

Variable How to get it
POSTGRES_USER Any username, e.g. colabs
POSTGRES_PASSWORD Any password
POSTGRES_DB Any db name, e.g. colabs_db
DATABASE_URL Update to match the three values above: postgresql://POSTGRES_USER:POSTGRES_PASSWORD@localhost:5432/POSTGRES_DB?schema=public
MINIO_ROOT_USER Any username, e.g. minioadmin
MINIO_ROOT_PASSWORD Any password
JWT_SECRET Any random string, 32+ characters
GITHUB_CLIENT_ID Create a GitHub OAuth App (see below)
GITHUB_CLIENT_SECRET Same OAuth App
GITHUB_API_TOKEN GitHub personal access token (see below)

GitHub OAuth App — go to github.com/settings/developers → New OAuth App:

  • Homepage URL: http://localhost:3000
  • Callback URL: http://localhost:8000/api/auth/github/callback
  • Copy the Client ID and generate a Client Secret into .env

GitHub API Token — go to github.com/settings/tokens → Generate classic token. No scopes needed for public repos.

3. Start infrastructure

docker compose up -d

Starts PostgreSQL on :5432, Redis on :6379, and MinIO on :9000 (console at :9001).

4. Run migrations & seed

npm run db:migrate
npm run db:generate
npm run db:seed

5. Start the server

npm run dev

Server: http://localhost:8000 Health check: http://localhost:8000/health

API Documentation

Interactive API docs are available at http://localhost:8000/api/docs once the server is running.

The docs cover all endpoints, request/response schemas, auth requirements, and let you test requests directly from the browser.

Available Scripts

npm run dev          # Start dev server with hot reload
npm run build        # Compile TypeScript to dist/
npm run start        # Run compiled production build
npm run db:migrate   # Run Prisma migrations
npm run db:generate  # Regenerate Prisma client
npm run db:studio    # Open Prisma Studio (database GUI)
npm run db:seed      # Seed initial data
npm run test         # Run tests
npm run lint         # Lint with ESLint

Health Check

GET http://localhost:8000/health

Returns { "status": "ok" } — use this to confirm the server is up.

Project Structure

src/
├── app.ts
├── config/env.ts
├── lib/
│   ├── prisma.ts
│   ├── redis.ts
│   ├── s3.ts
│   └── github.ts
├── middleware/
│   ├── auth.ts
│   ├── errorHandler.ts
│   └── rateLimiter.ts
└── modules/
    ├── auth/
    ├── users/
    ├── projects/
    ├── issues/
    ├── gigs/
    ├── proposals/
    └── teams/

prisma/
├── schema.prisma
└── seed.ts
docker-compose.yml

Contributing

Part of the SpaceYaTech community. PRs welcome!

  1. Fork the repo
  2. Create a branch: git checkout -b feat/your-feature
  3. Commit: git commit -m 'feat: add your feature'
  4. Push and open a Pull Request

License

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

You are free to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software, subject to the conditions in the license.