🛠️ Setup and Documentation

This guide provides everything you need to set up, run, and understand the Operant Project Management System

---

🚀 Quick Start (Docker)

The easiest way to get the database running is via Docker:

docker-compose up -d

This starts a PostgreSQL instance on localhost:5432.

---

🐍 Backend Setup (Django + GraphQL)

1. Environment Config

Create a .env file in the backend/ directory:

DEBUG=True
SECRET_KEY=your-secret-key-here
DATABASE_URL=postgres://operant_user:operant_password@localhost:5432/operant_db

2. Installation

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

3. Database Migrations

python manage.py makemigrations
python manage.py migrate

4. Run Server

python manage.py runserver

API available at: http://localhost:8000/graphql/

---

⚛️ Frontend Setup (Next.js + Apollo)

1. Environment Config

Create a .env.local file in the frontend/ directory:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_publishable_key
CLERK_SECRET_KEY=your_secret_key
NEXT_PUBLIC_API_URL=http://localhost:8000/graphql/
NEXT_PUBLIC_CLERK_SIGN_IN_URL="/sign-in"
NEXT_PUBLIC_CLERK_SIGN_UP_URL="/sign-up"
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL="/"
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL="/"

2. Installation

cd frontend
pnpm install  # or npm install

3. Run Development Server

pnpm dev

App available at: http://localhost:3000

---

📖 API Reference

Core Schema

• Organizations: Managed by slug
• Projects: Linked to Organizations. Supports statuses: ACTIVE, COMPLETED, ON_HOLD
• Tasks: Kanban-style tasks with statuses: TODO, IN_PROGRESS, DONE
• Comments: Comments on tasks

Key Queries

• organization(slug: String!): Fetches org info and basic stats
• projects(orgSlug: String!): Lists all projects with completion rates
• project(id: ID!): Detailed project view including tasks
• task(id: ID!): Detailed task view including comments

Key Mutations

• createProject: Initialize a new project
• updateProject: Edit name, description, or status
• createTask: Add task to project
• updateTask: Edit title, description, or status
• createComment: Add feedback to a specific task

---

📑 Technical Summary

Architecture Decisions

1. Multi-tenancy: Built this so different companies (tenants) can use the same app securely. Every time someone asks for data, the system double-checks: "Does this user actually belong to this company?" This keeps everything private and separated
2. Authentication: Used Clerk to handle accounts and security
3. Frontend State: Used Apollo Client to make the app feel instant. When user move a card on the Kanban board, it shifts immediately without a loading spinner, and the server updates in the background
4. UI/UX: Built with Shadcn UI and Tailwind CSS to look professional and clean

Future Improvements

• Real-time Subscriptions: Use GraphQL subscriptions for live Kanban updates across team members
• File Attachments: Integrate AWS S3 or Supabase storage for task attachments
• Activity Logs: Track Every change (status moves, edits) in a dedicated activity feed.