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.
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
- 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
git clone https://github.com/call-0f-code/COC-API.git
cd COC-APIAPI 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.
Only needed if you are running the API outside Docker:
bun install
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.
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 devbun 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.
Generate and serve the API docs:
bun run apidoc # generates static docs into /docThen visit http://localhost:3000/docs while the server is running.
bun run test # runs: jest
| 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 |
- Fork the repo
- Create your feature branch (
git checkout -b feature/XYZ) - Commit your changes (
git commit -m "feat: add XYZ") - Push to the branch (
git push origin feature/XYZ) - Open a Pull Request
GNU General Public License v3.0
Happy coding!