Kanban

A Kanban full-stack application built with modern technologies, featuring JWT authentication, fine-grained authorization, real-time GraphQL subscriptions, and AI integration.

Quick summary

Backend: TypeScript, Bun runtime, Express + Apollo GraphQL Server
Frontend: Next.js (app router) React 19 + Zustand for client state
DB: PostgreSQL (Docker Compose) with migrations (drizzle / graphile-migrate)
PubSub: Redis (Docker Compose) for real-time subscriptions
Auth: JWT access + refresh tokens, cookie-based refresh where applicable

Screenshots

Landing Page	Dashboard

Project View	Task Dialog

Development workflow (local)

Clone the repo and install dependencies

git clone https://github.com/your-org/kanban.git
cd kanban
bun install

Start PostgreSQL and Redis (Docker Compose)

docker compose up -d
# Optional: show logs
docker compose logs -f postgres redis

Initialize the database (migrations)

Use graphile-migrate (project includes script aliases) or drizzle-kit where appropriate.

# Run migration tooling (graphile-migrate)
# npm/yarn: npm run gm migrate
bun run gm migrate

# Or use drizzle (if using drizzle migrations)
bun run drizzle:pull

Start backend and frontend in separate terminals

# Backend (from repo root)
bun run dev

# Frontend (inside client folder)
cd client && npm run dev

By default the frontend runs on http://localhost:3000 and backend on http://localhost:4000 (GraphQL at /graphql). Adjust ports via .env if needed.

Environment variables

Create a .env file from .env.example and set the values below. Example keys used by the app:

# Server
PORT=4000
NODE_ENV=development

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/kanban_db

# Redis
REDIS_URL=redis://localhost:6379

# JWT
JWT_ACCESS_SECRET=your-access-secret
JWT_REFRESH_SECRET=your-refresh-secret

# AI
GEMINI_API_KEY=your-gemini-api-key

# Optional
LOG_LEVEL=info

Note: API_BASE_URL is configured in client/src/lib/gql.ts and defaults to http://localhost:4000.

Migrations

graphile-migrate: commands are exposed in the root package.json as gm scripts (e.g., bun run gm migrate, bun run gm commit).
drizzle-kit: use bun run drizzle:pull or related drizzle scripts in package.json when applicable.

Testing

Run backend tests from repo root (uses Jest):

bun run test

Frontend tests (if present) live in client/ and can be run with the client's test script.

Linting & Formatting

# Backend lint
bun run lint

# Frontend lint
cd client && npm run lint

Docker

Development uses docker compose for PostgreSQL. To run full development stack:

docker compose up --build

To stop and clean volumes (use with caution):

docker compose down -v

Useful commands

bun run dev — start backend in dev mode
cd client && npm run dev — start Next.js frontend
bun run gm migrate — apply migrations
bun run test — run backend tests
bun run build — build backend

Architecture notes

src/graphql contains GraphQL schemas and resolvers. Resolvers delegate to src/services and src/models.
src/models/drizzle contains typed DB access using Drizzle ORM; src/models/raw contains light wrappers for ad-hoc SQL.
client/src/store uses domain-focused Zustand stores (auth, workspace, notifications, ui, etc.) and a small compatibility wrapper useAppStore for incremental migration.
API helper client/src/lib/gql.ts centralizes the GraphQL endpoint and helper graphqlRequest() used across services.

Contributing

Fork and create a feature branch
Add tests for new behavior
Run migrations and seed data locally when needed
Follow lint rules and run bun run lint

Troubleshooting

Database connection issues: ensure Docker container is running and DATABASE_URL matches container port.
GraphQL schema errors: restart the server after updating schema files and run migrations if DB schema changed.
Auth/Logout issues: client uses /auth/logout (REST) for cookie-based logout; ensure cookies are passed when testing.

If you want, I can also add a small CONTRIBUTING.md and a DEVELOPMENT.md with exact commands for common dev tasks.

🚀 Features

Core Functionality

JWT Authentication: Secure login/logout with refresh tokens and device tracking
Complex Authorization: Multi-level permission system (Workspace → Project → Task)
Real-time Updates: GraphQL subscriptions for live task status changes
Task Management: Complete CRUD operations with automatic notifications
AI Integration: Gemini API for task summarization and generation
PostgreSQL Database: Robust data modeling with Docker deployment

Technical Stack

Runtime: Bun (both runtime and package manager)
Framework: Express.js with TypeScript
API: GraphQL (Apollo Server) with REST endpoints for auth
Database: PostgreSQL with raw SQL queries
Authentication: JWT with separate access/refresh tokens
Real-time: GraphQL Subscriptions with PubSub
Security: Helmet, CORS, rate limiting, input validation
Logging: Winston dual-logging (File + Database)

🏗️ Architecture

Authorization Hierarchy

Workspace (OWNER/MEMBER/VIEWER)
├── Project (PROJECT_LEAD/CONTRIBUTOR/PROJECT_VIEWER)
    └── Task (Assigned users with notifications)

API Structure

REST Endpoints: Authentication (/auth/login, /auth/logout, /auth/refresh)
GraphQL: All business logic (workspaces, projects, tasks, notifications, AI features)
Subscriptions: Real-time task status updates

📋 Prerequisites

Bun: curl -fsSL https://bun.sh/install | bash
Docker & Docker Compose: For PostgreSQL database
Node.js 20+: For compatibility

🚀 Quick Start

1. Clone and Install

git clone <https://github.com/your-org/kanban.git>
cd kanban
bun install

2. Environment Setup

cp .env.example .env
# Edit .env with your configuration

3. Database Setup

# Start PostgreSQL with Docker
docker compose up --build -d

# Initialize database schema
bun run db:migrate

4. Start the Application

# Backend (Terminal 1)
bun run dev

# Frontend (Terminal 2)
cd client && npm run dev

5. Access the Application

Frontend: http://localhost:3000
GraphQL Playground: http://localhost:4000/graphql
Health Check: http://localhost:4000/health

🔧 Configuration

Environment Variables (.env)

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5433/collaboration_db

# JWT
JWT_ACCESS_SECRET=your-access-secret-key
JWT_REFRESH_SECRET=your-refresh-secret-key
JWT_ACCESS_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d

# Server
PORT=4000
NODE_ENV=development

# AI (Optional)
GEMINI_API_KEY=your-gemini-api-key

# Logging
LOG_LEVEL=info
LOG_FILE=logs/audit.log

📚 API Documentation

Authentication (REST)

# Login
POST /auth/login
{
  "email": "user@example.com",
  "password": "password"
}

# Logout
POST /auth/logout

# Refresh Token
POST /auth/refresh

# Update Password
POST /auth/update-password
{
  "currentPassword": "oldpass",
  "newPassword": "newpass"
}

GraphQL Examples

Create Workspace

mutation {
  createWorkspace(name: "My Workspace") {
    id
    name
    ownerId
  }
}

Create Task with Notifications

mutation {
  createTask(
    projectId: "project-uuid"
    title: "Implement feature"
    description: "Detailed description"
    assignedToIds: ["user-uuid"]
  ) {
    id
    title
    status
    assignedUsers {
      id
      email
    }
  }
}

Real-time Task Updates

subscription {
  taskStatusUpdated(workspaceId: "workspace-uuid") {
    id
    title
    status
    updatedAt
  }
}

AI Task Summarization

query {
  summarizeTask(description: "Long task description here...")
}

🧪 Testing

# Run all tests
bun run test

# Run with coverage
bun run test:coverage

# Run specific test file
bun run test auth.test.ts

🐳 Docker Deployment

Development

docker compose up --build

Production

docker build -t collaboration-platform .
docker run -p 4000:4000 collaboration-platform

🔒 Security Features

JWT Authentication: Stateless authentication with refresh tokens
Device Tracking: IP address and user agent logging
Rate Limiting: Protection against brute force attacks
Input Validation: Joi schemas for all inputs
Security Headers: Helmet.js configuration
Audit Logging: Comprehensive security and activity logs
CORS: Configured cross-origin policies

📊 Database Schema

Core Tables

users: User accounts with global status (ACTIVE/BANNED/ADMIN)
workspaces: Collaborative spaces with ownership
workspace_members: Membership with roles (OWNER/MEMBER/VIEWER)
projects: Work containers within workspaces
project_memberships: Project-specific roles (PROJECT_LEAD/CONTRIBUTOR/PROJECT_VIEWER)
tasks: Work items with assignment and status tracking
notifications: User notifications with delivery status
user_devices: Session management and device tracking
audit_logs: Security and activity logging

🤖 AI Integration

Features

Task Summarization: Generate concise summaries from detailed descriptions
Task Generation: Create structured task lists from high-level prompts
Intelligent Assistance: Powered by Google Gemini API

Usage

# Summarize a task
query {
  summarizeTask(description: "Implement user authentication with JWT tokens, including password hashing, refresh tokens, and device tracking...")
}

# Generate tasks from prompt
mutation {
  generateTasksFromPrompt(
    projectId: "project-uuid"
    prompt: "Build a user registration system"
  )
}

📈 Monitoring & Logging

Log Categories

Security Logs: Authentication failures, admin actions, bans
Activity Logs: Task lifecycle, project/workspace management
System Logs: Errors, critical events
User Logs: Session management, device tracking

Log Destinations

File: logs/audit.log with Winston formatting
Database: audit_logs table for compliance and querying

🚀 Production Deployment

Environment Setup

export NODE_ENV=production
export DATABASE_URL=postgresql://prod-user:prod-pass@prod-host:5432/prod-db
export JWT_ACCESS_SECRET=strong-production-secret
export GEMINI_API_KEY=your-production-api-key

Build & Deploy

bun run build
bun run start

🛠️ Development

Project Structure

├── src/
│   ├── config/          # Database configuration
│   ├── graphql/
│   │   ├── schemas/     # GraphQL type definitions
│   │   └── resolvers/   # GraphQL resolvers
│   ├── middleware/      # Express middleware
│   ├── models/          # Database models
│   ├── routes/          # REST API routes
│   ├── services/        # External services (AI)
│   ├── types/           # TypeScript definitions
│   └── utils/           # Utilities (auth, logger)
├── client/              # Next.js frontend
├── database-schema.sql  # PostgreSQL schema
├── docker-compose.yml   # Docker configuration
└── jest.config.js       # Test configuration

Available Scripts

bun run dev          # Start development server
bun run build        # Build for production
bun run start        # Start production server
bun run test         # Run test suite
bun run lint         # Run ESLint
bun run db:migrate   # Initialize database

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Troubleshooting

Common Issues

Database Connection Failed

# Ensure Docker containers are running
docker compose ps

# Check database logs
docker compose logs postgres

GraphQL Schema Errors

# Validate schema
bun run dev  # Check console for schema validation errors

Test Failures

# Clean test database
docker compose down -v
docker compose up --build -d
bun run test

AI Features Not Working

# Verify GEMINI_API_KEY in .env
echo $GEMINI_API_KEY

📞 Support

For questions or issues:

Check the troubleshooting section above
Review the API documentation
Create an issue with detailed information
Include environment details and error logs

Built with ❤️ using Bun, TypeScript, GraphQL, and PostgreSQL

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
.github/workflows		.github/workflows
client		client
migrations		migrations
screenshots		screenshots
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
.gmrc		.gmrc
Dockerfile		Dockerfile
README.md		README.md
bun.lock		bun.lock
docker-compose.yml		docker-compose.yml
drizzle.config.ts		drizzle.config.ts
index.ts		index.ts
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

switch247/kanban

Folders and files

Latest commit

History

Repository files navigation