Project Collaboration & Workflow API

A production-grade backend API for multi-user project collaboration, featuring authentication, authorization, rate limiting, auditing, and workflow management.

Features

• 🔐 JWT-based Authentication - Secure token-based auth with refresh tokens
• 👥 Multi-tenant Organizations - Support for multiple organizations per user
• 🎯 Role-Based Access Control - Granular permissions at org and project levels
• 📊 Project & Task Management - Full workflow support with status transitions
• 📝 Activity Audit Trail - Immutable logs of all system actions
• ⚡ Rate Limiting - Token bucket strategy for API protection
• 📈 Prometheus Metrics - Built-in monitoring and observability
• 🔍 Structured Logging - JSON logging with correlation IDs
• ✅ Input Validation - Schema-based validation for all requests
• 🐳 Docker Support - PostgreSQL container for easy setup

Tech Stack

• Language: Go 1.25
• Framework: Chi router
• Database: PostgreSQL 15
• Auth: JWT with golang-jwt/jwt
• Validation: go-playground/validator
• Logging: zerolog
• Metrics: Prometheus
• Containerization: Docker & Docker Compose

Getting Started

Prerequisites

• Go 1.25+
• Docker & Docker Compose
• Make (optional)

Installation

1. Clone the repository

   git clone <repository-url>
   cd api-architecture

2. Create environment file

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

3. Start PostgreSQL

   docker-compose up -d

4. Install dependencies

   go mod download

5. Run the application

   go run cmd/server/main.go

   Or using Make:

   make run

The API will be available at http://localhost:8080

API Documentation

• OpenAPI Spec: See api/openapi.yaml
• Health Check: GET /health
• Readiness Check: GET /ready
• Metrics: GET /metrics

Auth Sequence Diagram

Project Structure

.
├── api/                    # OpenAPI specification
├── cmd/
│   └── server/            # Application entry point
├── internal/              # Private application code
│   ├── api/v1/           # API routes and handlers
│   │   ├── handler/      # HTTP request handlers
│   │   ├── middleware/   # HTTP middleware
│   │   └── routes.go     # Route definitions
│   ├── auth/             # Authentication logic
│   ├── config/           # Configuration management
│   ├── logger/           # Logging utilities
│   ├── model/            # Domain models
│   ├── utils/            # Helper functions
│   ├── repository.go     # Data access layer
│   ├── service.go        # Business logic layer
│   ├── validator.go      # Request validation
│   └── response.go       # Response helpers
├── migrations/            # Database migrations
├── tests/                 # Test files
├── docker-compose.yml     # Docker services
├── Makefile              # Build automation
└── README.md             # This file

API Endpoints

Authentication

• POST /api/v1/auth/register - Register new user
• POST /api/v1/auth/login - Login user
• POST /api/v1/auth/refresh - Refresh access token
• POST /api/v1/auth/logout - Logout user

Users

• GET /api/v1/users/me - Get current user profile
• PATCH /api/v1/users/me - Update profile
• DELETE /api/v1/users/me - Delete account

Organizations

• POST /api/v1/organizations - Create organization
• GET /api/v1/organizations - List organizations
• GET /api/v1/organizations/{id} - Get organization
• PATCH /api/v1/organizations/{id} - Update organization
• DELETE /api/v1/organizations/{id} - Delete organization

Organization Members

• POST /api/v1/organizations/{id}/members - Add member
• GET /api/v1/organizations/{id}/members - List members
• PATCH /api/v1/organizations/{id}/members/{user_id} - Update member role
• DELETE /api/v1/organizations/{id}/members/{user_id} - Remove member

Projects

• POST /api/v1/organizations/{id}/projects - Create project
• GET /api/v1/organizations/{id}/projects - List projects
• GET /api/v1/projects/{id} - Get project
• PATCH /api/v1/projects/{id} - Update project
• DELETE /api/v1/projects/{id} - Delete project

Tasks

• POST /api/v1/projects/{id}/tasks - Create task
• GET /api/v1/projects/{id}/tasks - List tasks
• GET /api/v1/tasks/{id} - Get task
• PATCH /api/v1/tasks/{id} - Update task
• DELETE /api/v1/tasks/{id} - Delete task

Task Management

• POST /api/v1/tasks/{id}/assignees - Assign user
• DELETE /api/v1/tasks/{id}/assignees/{user_id} - Unassign user
• POST /api/v1/tasks/{id}/comments - Add comment
• GET /api/v1/tasks/{id}/comments - List comments
• DELETE /api/v1/comments/{id} - Delete comment

Activities

• GET /api/v1/projects/{id}/activities - Get project activities
• GET /api/v1/tasks/{id}/activities - Get task activities

Testing

Run tests:

go test -v ./...

Run tests with coverage:

make test-coverage

Configuration

Configuration is loaded from environment variables. See .env.example for all available options.

Key configuration:

• JWT_SECRET - Secret key for JWT signing (change in production!)
• DB_* - Database connection parameters
• RATE_LIMIT_* - Rate limiting thresholds
• LOG_LEVEL - Logging level (debug, info, warn, error)

Database Schema

The database schema is automatically applied on first startup via Docker. See migrations/001_init_schema.sql for the complete schema.

Key tables:

• users - User accounts
• organizations - Top-level tenants
• org_memberships - User-organization relationships
• projects - Projects within organizations
• project_memberships - User-project relationships
• tasks - Work items
• task_assignments - Task assignees
• task_comments - Task discussions
• activities - Audit log
• refresh_tokens - Session management

Rate Limiting

Rate limits are enforced per IP address:

• General endpoints: 100 requests/min
• Auth endpoints: 10 requests/min
• Write operations: 60 requests/min
• Bulk operations: 20 requests/min

Security

• Passwords hashed with bcrypt (cost 12)
• JWT tokens with short expiration (15 min)
• Refresh token rotation on use
• SQL injection prevention via parameterized queries
• Input validation on all endpoints
• CORS configuration
• Request ID tracking

Monitoring

Prometheus metrics are exposed at /metrics:

• HTTP request counts by method, path, and status
• Request duration histograms
• Database connection pool stats

Development

Building

make build

Running locally

make run

Docker commands

make docker-up    # Start services
make docker-down  # Stop services
make docker-clean # Stop and remove volumes