Club IQ

---

Overview

Club IQ is a full-stack platform for managing clubs: members, events, attendance, authentication, and more.

It includes:

• Flask REST API
• Next.js frontend
• PostgreSQL relational DB
• Full Docker environment
• Clerk authentication
• Scalable architecture for real-world clubs and organizations

---

Table of Contents

• Club IQ
• Overview
• Table of Contents
• Project Structure
• Setup & Installation
• Step 1 — Install Docker
• Step 2 — (Recommended) Setup Node in WSL using NVM
  • Install NVM
  • Install Node (LTS)
  • Verify WSL paths
• Step 3 — Install Make
• Step 4 — Creating the Containers
  • Build all services:
  • Run containers (attached):
  • Detached mode:
• Manual Setup
• Frontend Setup (Next.js)
• API Reference
  • Base URLs
  • Endpoint Documentation. All blueprints for backend
• Contribution Guide
• License

---

Project Structure

ClubIQ/
├── Backend/
│   ├── Dockerfile
│   ├── entrypoint.sh
│   ├── requirements.txt
│   ├── backend.env.example
│   ├── postgres.env.example
│   └── app/
│       ├── models.py
│       └── ...
│
├── Frontend/
│   ├── Dockerfile
│   ├── package.json
│   ├── frontend.env.example
│   └── src/
│
├── docker-compose.yml
├── Makefile
├── .dockerignore
└── Docker.md

---

Setup & Installation

Works on Windows, and Linux. Follow the steps as listed — skipping ahead is how people summon bugs from the abyss.

---

Step 1 — Install Docker

We recommend installing Docker Desktop as it not only installs Docker Desktop but also the Docker Engine, Docker CLI, and Docker Compose.

Download: https://www.docker.com/products/docker-desktop/

During installation:

• Enable Hyper-V / Virtualization
• Enable WSL2 backend

After installation, make sure the Docker Daemon / docker.service is running in the background otherwise none of the make or docker commands will work.

Note: Using Docker Desktop / Podman Desktop is completely optional but is recommended since it makes it easy to manage your containers.

---

Step 2 — (Recommended) Setup Node in WSL using NVM

On Windows, use WSL for Node development or you’ll meet npm’s mood swings.

Install NVM

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc

Install Node (LTS)

nvm install --lts
nvm use --lts

Verify WSL paths

which node
which npm
node -v
npm -v

Paths must not point to Windows directories.

---

Step 3 — Install Make

gnu make is optional but we highly recommend installing it.

Install it by either visiting the official Make website or using your package manager.

---

Step 4 — Creating the Containers

View the our Docker.md file for the full installation steps.

Build all services:

make build

Run containers (attached):

make up

Detached mode:

make up-detached

---

Manual Setup

If you want to setup the project without using Docker:

cd Backend

python -m venv venv

# Activate:
source venv/bin/activate      # Linux/macOS
venv\Scripts\activate         # Windows

pip install -r requirements.txt

flask run

Environment variables are read from the process environment.

For Docker workflows, use Backend/backend.env, Frontend/frontend.env and Backend/postgres.env (see Docker Guide).

---

Frontend Setup (Next.js)

cd Frontend
npm install
npm run dev

Frontend runs on:

http://localhost:3000

---

API Reference

Base URLs

• Dev: http://localhost:5000/api
• Prod: https://yourdomain.com/api

---

Endpoint Documentation. All blueprints for backend

• V1
• Authentication
• Clubs
• Members
• Activities
• Rating
• Invitation
• Health

---

Contribution Guide

All contributions are welcome! But kindly follow the contribution guidelines.

---

License

MIT License.