Skip to content

README.md

Latest commit

 

History

History
243 lines (191 loc) · 8.16 KB

README.md

File metadata and controls

243 lines (191 loc) · 8.16 KB

COC-API

This repository contains the shared Express.js API for the backends of our Coding Club's websites, backed by PostgreSQL (via Prisma) and Supabase storage. We use Bun as our runtime.

📂 Folder Structure

COC-API/
├── prisma/                  # Prisma schema and migration files
│   ├── schema.prisma
│   └── migrations/          # auto-generated by `bun run migrate`
│
├── src/
│   ├── config/              # environment/configuration loaders
│   │
│   ├── db/                  # database client initialization
│   │
│   ├── routes/              # Express route definitions
│   │   ├── index.ts         # main router — mounts all sub-routers under /api/v1
│   │   ├── members.ts
│   │   ├── projects.ts
│   │   ├── achievements.ts
│   │   ├── interviews.ts
│   │   ├── topics.ts
│   │   ├── questions.ts
│   │   ├── progress.ts
│   │   ├── site-content.ts
│   │   └── email.ts
│   │
│   ├── controllers/         # controllers: take req → call services → send res
│   │   ├── member.controller.ts
│   │   ├── project.controller.ts
│   │   ├── achievement.controller.ts
│   │   ├── interview.controller.ts
│   │   ├── topic.controller.ts
│   │   ├── question.controller.ts
│   │   ├── progress.controller.ts
│   │   ├── site-content.controller.ts
│   │   └── emailTemplate.controller.ts
│   │
│   ├── services/            # business logic / Prisma queries
│   │   ├── member.service.ts
│   │   ├── project.service.ts
│   │   ├── achievement.service.ts
│   │   ├── interview.service.ts
│   │   ├── topic.service.ts
│   │   ├── question.service.ts
│   │   ├── progress.service.ts
│   │   ├── site-content.service.ts
│   │   └── emailTemplate.service.ts
│   │
│   ├── utils/               # shared helpers
│   │   ├── apiError.ts      # custom error class and global error handler
│   │   ├── imageUtils.ts    # image upload / Supabase storage helpers
│   │   ├── logger.ts        # Winston logger instance
│   │   └── supabaseClient.ts
│   │
│   ├── app.ts               # configure Express app, mount routes, error handler
│   └── server.ts            # start HTTP server
│
├── tests/                   # unit tests (Jest + ts-jest)
│   ├── Member.test.ts
│   ├── Project.test.ts
│   ├── Achievement.test.ts
│   ├── Interview.test.ts
│   ├── Topics.test.ts
│   ├── Question.test.ts
│   ├── Progress.test.ts
│   ├── SiteContent.test.ts
│   └── imageUtils.test.ts
│
├── docker/                  # Docker Compose stacks
│   ├── docker-compose.yml   # ★ Master stack — all platforms together
│   ├── coc-member/          # Full COC Member platform stack
│   │   ├── docker-compose.yml
│   │   ├── .env.local.backend.example
│   │   └── .env.local.frontend.example
│   ├── coc-admin/           # Full COC Admin platform stack
│   │   ├── docker-compose.yml
│   │   ├── .env.local.backend.example
│   │   └── .env.local.frontend.example
│   └── callofcode.in/       # Full callofcode.in website stack
│       ├── docker-compose.yml
│       └── .env.local.frontend.example
│
├── .env.example             # API environment variable template
├── docker-compose.yml       # API-only dev stack (standalone)
├── package.json
└── tsconfig.json

🚀 Getting Started

Prerequisites

  • Docker Desktop or Docker Engine + Compose plugin v2.22+ — required for all workflows
  • Bun — only needed if you want to run the API outside Docker

1. Clone the repo

git clone https://github.com/call-0f-code/COC-API.git
cd COC-API

2. Configure environment

API credentials (required by all stacks):

cp .env.example .env.local
Variable Description
DATABASE_URL Supabase connection-pooling URL (Prisma runtime)
DIRECT_URL Direct DB connection URL (Prisma Migrate)
SUPABASE_URL Your Supabase project URL
SUPABASE_SERVICE_ROLE_KEY Supabase service-role secret key
NODE_ENV development | production

Platform-specific credentials (only needed for the stack you're running):

# COC Member
cp docker/coc-member/.env.local.backend.example  docker/coc-member/.env.local.backend
cp docker/coc-member/.env.local.frontend.example docker/coc-member/.env.local.frontend

# COC Admin
cp docker/coc-admin/.env.local.backend.example   docker/coc-admin/.env.local.backend
cp docker/coc-admin/.env.local.frontend.example  docker/coc-admin/.env.local.frontend

# callofcode.in
cp docker/callofcode.in/.env.local.frontend.example docker/callofcode.in/.env.local.frontend

Edit each file and replace the change_me_* and your_* placeholders with real values. See DOCKER.md for a full variable reference.

3. Install dependencies (local dev only)

Only needed if you are running the API outside Docker:

bun install

4. Local development (Docker)

The project ships five Docker Compose stacks. Choose the one you need:

# ★ All platforms at once (recommended for full-stack development)
docker compose -f docker/docker-compose.yml up --watch

# API only (for coc-api development)
docker compose up --build

# Full COC Member platform
cd docker/coc-member && docker compose up --build

# Full COC Admin platform
cd docker/coc-admin  && docker compose up --build

# Full callofcode.in website
cd docker/callofcode.in && docker compose up --build

All stacks automatically run Prisma migrations on startup and use health checks to ensure correct service startup order.

📖 See DOCKER.md for full details — environment files, watch mode, port mappings, common commands, and troubleshooting.

5. Initialize / run migrations

For a brand-new database:

bun run migrate:first   # runs: bunx prisma migrate dev --name init
bun run generate        # runs: bunx prisma generate

For subsequent schema changes:

bun run migrate         # runs: bunx prisma migrate dev

6. Start the server

bun run start

The server listens on http://localhost:3000 by default.
All API routes are prefixed with /api/v1, e.g. http://localhost:3000/api/v1/members.

7. API Documentation

Generate and serve the API docs:

bun run apidoc          # generates static docs into /doc

Then visit http://localhost:3000/docs while the server is running.

8. Run tests

bun run test            # runs: jest

📦 Scripts

Command Description
bun run start Start the server (bun src/server.ts)
bun run local Spin up local Docker environment and seed the DB
bun run migrate Run pending Prisma migrations in development
bun run migrate:first Apply initial migration (--name init)
bun run generate Regenerate Prisma client
bun run test Run all tests with Jest
bun run apidoc Generate API documentation into /doc
bun run lint Lint src/ with ESLint
bun run lint:fix Lint and auto-fix src/
bun run format Format src/ with Prettier

🤝 Contributing

  1. Fork the repo
  2. Create your feature branch (git checkout -b feature/XYZ)
  3. Commit your changes (git commit -m "feat: add XYZ")
  4. Push to the branch (git push origin feature/XYZ)
  5. Open a Pull Request

📜 License

GNU General Public License v3.0

Happy coding!