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 platformcd docker/coc-member && docker compose up --build
# Full COC Admin platformcd docker/coc-admin && docker compose up --build
# Full callofcode.in websitecd 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!