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

/
├── prisma/                  # Prisma schema and migration files
│   ├── schema.prisma
│   └── migrations/          # auto-generated by `bun run migrate`
│
├── seed/
│   └── dump.sql             # local seed file loaded by the setup script
│
├── scripts/
│   └── setup-local.sh       # automates local environment bring-up
│
├── 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
│
├── .env.example             # template for environment variables
├── package.json
└── tsconfig.json

🚀 Getting Started

Prerequisites

• Install Bun on your machine.
• Install Docker & Docker Compose for the local database.

1. Clone the repo

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

2. Install dependencies

bun install

3. Configure environment

Copy .env.example to .env and fill in the required values:

cp .env.example .env

Key variables:

Variable	Description
DATABASE_URL	Supabase connection-pooling URL (used by Prisma at runtime)
DIRECT_URL	Direct DB connection URL (used by Prisma Migrate)
SUPABASE_URL	Your Supabase project URL
SUPABASE_SERVICE_ROLE_KEY	Supabase service-role secret key
SESSION_POOLER	Session-mode pooler URL — used by setup-local.sh for pg_dump (IPv4)
NODE_ENV	development | production

4. Local development (Docker)

The setup script starts a local Postgres container and seeds it automatically:

bun run local

See LOCAL_DEVELOPMENT.md for full details, flags, 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!