Skip to content

README.md

Latest commit

 

History

History
920 lines (773 loc) · 35.9 KB

README.md

File metadata and controls

920 lines (773 loc) · 35.9 KB
Raw

WorkSynapse Logo

🧠 WorkSynapse

AI-Powered Intelligent Company Operating System

Features • Architecture • Tech Stack • Project Structure • Security Features • Setup & Installation • Multi-Tenancy • Work Management • API Docs •

Version License PRs Welcome

🎯 Overview

WorkSynapse is a production-grade, full-stack intelligent company operating system designed to revolutionize how teams collaborate, manage projects, and boost productivity. It seamlessly integrates AI-powered agents, real-time communication, project management, and automated time tracking into one unified platform.

🌟 What Makes WorkSynapse Unique?

Feature Description
🤖 AI Agents Intelligent agents that automate project management, task generation, and developer assistance
🗂️ Asana-style Work Management Sections, subtasks, followers, dependencies, custom fields, recurring tasks, List/Calendar/Timeline views, portfolios, goals/OKRs, forms, automation rules, templates, approvals, and an inbox
⏱️ Auto Time Tracking Desktop app with work detection model for automatic productivity tracking
💬 Real-time Chat Secure WebSocket-based team communication with channels
📊 Smart Dashboards Analytics and insights powered by AI
🔒 Enterprise Security JWT auth, RBAC, rate limiting, and zero-trust architecture

✨ Features

💬 Company Internal Chat

  • Real-time messaging via WebSockets
  • Channel-based communication
  • Direct messages & group chats
  • Message search & history
  • File sharing & attachments
  • Presence indicators (online/offline)
  • @ mentions & notifications

📋 Trello-Style Project Boards

  • Drag-and-drop Kanban boards
  • Custom columns & workflows
  • Card labels, checklists, due dates
  • Board templates
  • Activity timeline
  • Board sharing & permissions

🎯 Task & Sprint Management

  • Sprint planning & tracking
  • Backlog management
  • Story points & velocity
  • Burndown charts
  • Task dependencies
  • Time estimates vs actuals

🤖 AI Project Manager Agents

  • Project Manager Agent: Creates roadmaps, milestones, and tracks progress
  • Task Generator Agent: Converts feature descriptions into actionable tasks
  • Dev Assistant Agent: Answers code questions, suggests fixes, explains logic
  • Productivity Agent: Analyzes work patterns and provides insights

🧠 Smart Task Auto-Assignment

  • AI analyzes team skills & workload
  • Automatic task distribution
  • Balanced workload management
  • Skill-based matching
  • Priority-aware assignment

⏰ Work Detection & Auto Time Tracking

  • Desktop activity monitoring
  • Automatic timer start/stop
  • Application usage tracking
  • Idle time detection
  • Productivity scoring
  • Daily/weekly reports

📝 Notes, Sharing & Forwarding

  • Rich text editor
  • Markdown support
  • Note organization (folders/tags)
  • Share with team members
  • Forward to channels/DMs
  • Version history

🏗️ Architecture

WorkSynapse follows a Modular Monorepo architecture combining Event-Driven and Layered patterns for scalability and maintainability.

              ┌─────────────────────────────────────────────────────────────────┐
              │                          CLIENT LAYER                           │
              ├─────────────────┬─────────────────┬─────────────────────────────┤
              │     Web App     │   Desktop App   │       Mobile (Future)       │
              │   (React/TS)    │   (Electron)    │                             │
              └─────────────────┴───┬─────────────┴───┬─────────────────────────┘
                                    │                 │
                                    ▼                 ▼
              ┌─────────────────────────────────────────────────────────────────┐
              │                           API GATEWAY                           │
              │                 (FastAPI + Security Middleware)                 │
              │            Rate Limiting │ JWT Auth │ RBAC │ Logging            │
              └───────────────────────────────┬─────────────────────────────────┘
                                              │
                          ┌───────────────────┼───────────────────┐
                          ▼                   ▼                   ▼
                  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
                  │    REST API     │ │    WebSocket    │ │    Webhooks     │
                  │    Endpoints    │ │     Handler     │ │  (GitHub/Jira)  │
                  └───────┬─────────┘ └───────┬─────────┘ └───────┬─────────┘
                          │                   │                   │
                          └───────────────────┼───────────────────┘
                                              ▼
              ┌─────────────────────────────────────────────────────────────────┐
              │                          SERVICE LAYER                          │
              ├─────────────────┬─────────────────┬─────────────────────────────┤
              │  User Service   │ Project Service │        Task Service         │
              │  Chat Service   │  Agent Service  │      Analytics Service      │
              └─────────────────┴───┬─────────────┴───┬─────────────────────────┘
                                    │                 │
                                    ▼                 ▼
              ┌─────────────────────────────────────────────────────────────────┐
              │                         MESSAGE BROKERS                         │
              ├─────────────────────────────┬───────────────────────────────────┤
              │            Kafka            │             RabbitMQ              │
              │      (Event Streaming)      │        (Task Queue/Celery)        │
              │   - Chat messages           │      - AI Agent jobs              │
              │   - Activity logs           │      - Notifications              │
              │   - System events           │      - Background tasks           │
              └─────────────────────────────┴───────────────────────────────────┘
                            │                                     │
                            ▼                                     ▼
                    ┌─────────────────┐                   ┌─────────────────┐
                    │      Redis      │                   │  Celery Workers │
                    │  - Caching      │                   │  - AI Agents    │
                    │  - Sessions     │                   │  - Emails       │
                    │  - Rate Limits  │                   │  - Analytics    │
                    │  - Presence     │                   │                 │
                    └─────────────────┘                   └─────────────────┘
                            │
                            ▼
              ┌─────────────────────────────────────────────────────────────────┐
              │                           DATA LAYER                            │
              ├─────────────────────────────────────────────────────────────────┤
              │                           PostgreSQL                            │
              │     Users │ Projects │ Tasks │ Messages │ WorkLogs │ Notes      │
              └─────────────────────────────────────────────────────────────────┘

🛠️ Tech Stack

Backend (backend/)

Technology Purpose
FastAPI High-performance async API framework
SQLAlchemy Async ORM with PostgreSQL
Pydantic Data validation & serialization
Celery Distributed task queue
Redis Caching, sessions, rate limiting
Kafka Event streaming
RabbitMQ Message broker for Celery
JWT + OAuth2 Authentication & authorization

Web App (web/)

Technology Purpose
React 18 UI library
TypeScript Type-safe JavaScript
Vite Build tool & dev server
Zustand State management
React Router Client-side routing
Socket.IO Real-time communication
Vanilla CSS Premium dark mode styling

Desktop App (desktop/)

Technology Purpose
Electron Cross-platform desktop framework
Python Activity detection scripts
TypeScript Main & renderer process

DevOps (devops/)

Technology Purpose
Docker Containerization
Kubernetes Orchestration
Prometheus Metrics collection
Grafana Monitoring dashboards

📁 Project Structure

worksynapse/
│
├── 📂 assets/                    # Global shared assets
│   ├── logos/                    # Brand logos
│   ├── icons/                    # UI icons
│   ├── illustrations/            # Decorative graphics
│   └── backgrounds/              # Background images
│
├── 📂 backend/                   # FastAPI Backend
│   ├── app/
│   │   ├── api/
│   │   │   ├── v1/
│   │   │   │   ├── routers/      # API endpoints
│   │   │   │   │   ├── auth.py   # Login, register, refresh
│   │   │   │   │   ├── users.py  # User CRUD
│   │   │   │   │   ├── projects.py
│   │   │   │   │   ├── tasks.py
│   │   │   │   │   ├── chat.py
│   │   │   │   │   ├── agents.py
│   │   │   │   │   ├── webhooks.py
│   │   │   │   │   ├── files.py
│   │   │   │   │   ├── notes.py
│   │   │   │   │   └── worklogs.py
│   │   │   │   └── endpoints/
│   │   │   │       └── websockets.py
│   │   │   └── deps.py           # Dependencies (Auth, RBAC)
│   │   │
│   │   ├── core/
│   │   │   ├── config.py         # Environment configuration
│   │   │   ├── security/         # JWT, password hashing, RBAC, anti-replay
│   │   │   ├── tenancy/          # Multi-tenant: context, registry, resolver,
│   │   │   │                     #   middleware, provisioning, bootstrap
│   │   │   ├── logging.py        # Structured logging
│   │   │   └── celery_app.py     # Celery configuration
│   │   │
│   │   ├── middleware/
│   │   │   └── security.py       # Security headers, rate limiting
│   │   │
│   │   ├── models/               # SQLAlchemy models
│   │   │   ├── base.py           # Tenant-app declarative Base
│   │   │   ├── master/           # Control-plane models (Organization registry)
│   │   │   ├── user/model.py
│   │   │   ├── project/model.py
│   │   │   ├── task/model.py
│   │   │   ├── chat/model.py
│   │   │   └── worklog/model.py
│   │   │
│   │   ├── schemas/              # Pydantic schemas
│   │   │   ├── user.py
│   │   │   ├── project.py
│   │   │   └── task.py
│   │   │
│   │   ├── services/             # Business logic
│   │   │   ├── base.py           # Generic CRUD
│   │   │   ├── user.py
│   │   │   ├── project.py
│   │   │   ├── redis_service.py  # Cache, sessions, locks
│   │   │   ├── kafka_service.py  # Event streaming
│   │   │   └── websocket_manager.py
│   │   │
│   │   ├── agents/               # AI Agents
│   │   │   ├── base.py           # Abstract base class
│   │   │   ├── security.py       # Prompt injection protection
│   │   │   ├── project_manager/
│   │   │   ├── task_generator/
│   │   │   ├── dev_assistant/
│   │   │   └── productivity/
│   │   │
│   │   ├── worker/               # Celery tasks
│   │   │   └── tasks/
│   │   │       ├── agents.py
│   │   │       ├── notifications.py
│   │   │       └── analytics.py
│   │   │
│   │   ├── database/
│   │   │   └── session.py        # Async SQLAlchemy setup
│   │   │
│   │   └── main.py               # FastAPI app entry
│   │
│   ├── Dockerfile
│   ├── requirements.txt
│   └── .env.example
│
├── 📂 web/                       # React Web App
│   ├── src/
│   │   ├── app/                  # App configuration
│   │   ├── features/             # Feature modules
│   │   │   ├── auth/
│   │   │   ├── projects/
│   │   │   ├── tasks/
│   │   │   ├── chat/
│   │   │   ├── notes/
│   │   │   ├── agents/
│   │   │   └── dashboard/
│   │   ├── components/           # Shared UI components
│   │   ├── hooks/                # Custom React hooks
│   │   ├── services/             # API clients
│   │   └── types/                # TypeScript types
│   ├── Dockerfile
│   ├── nginx.conf
│   └── package.json
│
├── 📂 desktop/                   # Electron Desktop App
│   ├── src/
│   │   ├── main/                 # Main process
│   │   ├── renderer/             # Renderer process (UI)
│   │   ├── work-detection/       # Python activity tracking
│   │   │   ├── activity_detector.py
│   │   │   ├── idle_tracker.py
│   │   │   └── app_monitor.py
│   │   └── timer/                # Timer components
│   └── package.json
│
├── 📂 shared-types/              # Shared TypeScript definitions
│   └── models/
│       └── index.ts
│
├── 📂 devops/                    # DevOps configurations
│   ├── k8s/
│   │   ├── backend-deployment.yaml
│   │   ├── celery-deployment.yaml
│   │   ├── database-deployment.yaml
│   │   ├── web-ingress.yaml
│   │   └── config-secrets.yaml
│   └── prometheus.yml
│
├── docker-compose.yml            # Full stack Docker setup
├── .env.example                  # Environment template
├── .gitignore                    # Git ignore rules
└── README.md                     # This file

🔐 Security Features

API Security

Feature Implementation
🔑 JWT Authentication Access + Refresh tokens with rotation
👥 RBAC Role-based access (Admin, Manager, Developer)
🚦 Rate Limiting Redis-backed request throttling
🛡️ Security Headers X-Frame-Options, CSP, HSTS
✅ Input Validation Pydantic schemas for all endpoints
🔒 Password Hashing Argon2 + bcrypt fallback

🔐 Anti-Replay Protection (NEW!)

WorkSynapse implements Zepto-style one-time API request protection where every API request can only be used once:

Feature Implementation
📝 HMAC-SHA256 Signatures All requests signed with secret key
🎫 UUID Nonces Each request has unique nonce
⏰ Timestamp Validation ±30 second window enforcement
🗄️ Redis Nonce Store 60-second TTL, distributed servers
🚫 IP Throttling Suspicious activity tracking & blocking

Required Headers for Protected Endpoints:

X-API-KEY: your-api-key
X-TIMESTAMP: 1706979600
X-NONCE: 123e4567-e89b-12d3-a456-426614174000
X-SIGNATURE: a1b2c3d4e5f6...

Error Codes:

Code Meaning
401 Missing headers or invalid API key
403 Invalid signature or IP blocked
408 Timestamp expired
409 Nonce already used (replay attack)
429 Rate limit exceeded

See backend/docs/ANTI_REPLAY_SECURITY.md for full documentation.

Real-time Security

Feature Implementation
🔐 WebSocket Auth JWT verification on handshake
📝 Message Validation Size limits, spam detection
⚡ Rate Limiting Per-user message throttling
🔏 Webhook Verification HMAC signature validation
🔄 Replay Protection Idempotency keys + Redis

Agent Security

Feature Implementation
🛑 Prompt Injection Detection Pattern-based filtering
🔧 Tool Whitelisting Per-agent allowed tools
🧹 Output Sanitization Sensitive data removal
📦 Context Isolation Separate session contexts

🚀 Setup & Installation

There are two ways to run WorkSynapse:

  • Path A — With Docker → everything (Postgres, Redis, RabbitMQ, Kafka, backend, web, monitoring) starts with a couple of commands. Recommended.
  • Path B — Without Docker → you install and run each service yourself. Good for active development on one component.

Whichever path you choose, do the Common Setup first.

🔧 Common Setup (both paths)

Prerequisites

Tool Docker path Manual path
Git ✅ ✅
Docker + Docker Compose ✅ —
Python — 3.11+
Node.js — 20+
PostgreSQL — 15+
Redis — 7+
RabbitMQ — 3+ (only if you run Celery)
Kafka — optional (event streaming)

1️⃣ Clone the repository

git clone https://github.com/your-org/worksynapse.git
cd worksynapse

2️⃣ Create the root .env (used by backend + Docker)

cp .env.example .env

Generate strong secrets and paste them into .env:

openssl rand -hex 32   # → SECRET_KEY
openssl rand -hex 24   # → SERVICE_API_KEY

Minimum values you must set in .env:

SECRET_KEY=<paste 32-byte hex>
SERVICE_API_KEY=<paste 24-byte hex>
POSTGRES_USER=worksynapse_user
POSTGRES_PASSWORD=<a strong password>
POSTGRES_DB=worksynapse
REDIS_PASSWORD=<a strong password>
RABBITMQ_USER=admin
RABBITMQ_PASSWORD=<a strong password>
GRAFANA_PASSWORD=<a strong password>
# Set DEBUG=true if you want the interactive API docs (see note below)
DEBUG=false
# Optional — enables AI agents
OPENAI_API_KEY=sk-...

⚠️ API docs are gated by DEBUG. /api/v1/docs and /api/v1/redoc are only served when DEBUG=true. In production keep it false.

🐳 Path A — With Docker (recommended)

1. Start the full stack

docker compose up -d --build
# older Docker: docker-compose up -d --build

# follow backend logs
docker compose logs -f backend

This launches: PostgreSQL, Redis, RabbitMQ, Zookeeper + Kafka, the FastAPI backend, Celery worker + beat, the web app, Prometheus and Grafana.

2. Create the database schema (run migrations)

The backend does not auto-create tables — apply Alembic migrations once the DB is healthy:

docker compose exec backend alembic upgrade head

3. Seed roles/permissions and create an admin user

# Seed default permissions + roles
docker compose exec backend python manage.py init

# Create your first admin (choose your own values)
docker compose exec backend python manage.py create_admin \
  --email admin@worksynapse.com --username admin \
  --password 'SecurePass123!' --superuser

4. (Optional) Enable multi-tenancy

See Multi-Tenancy Setup below.

5. Open the apps

Service URL
🌐 Web App http://localhost:80
🔌 API Docs (needs DEBUG=true) http://localhost:8000/api/v1/docs
❤️ Health check http://localhost:8000/health
🐰 RabbitMQ UI http://localhost:15672
📊 Prometheus http://localhost:9090
📈 Grafana http://localhost:3000

Useful Docker commands

docker compose ps                 # service status
docker compose logs -f backend    # tail a service
docker compose exec backend bash  # shell into the backend
docker compose down               # stop everything
docker compose down -v            # stop AND wipe all data volumes

💻 Path B — Without Docker (manual)

You need PostgreSQL, Redis and (for background jobs) RabbitMQ running locally.

1. Start the infrastructure services

On macOS with Homebrew, for example:

brew services start postgresql@15
brew services start redis
brew services start rabbitmq      # only if you run Celery

Create the database and a user matching your .env:

createdb worksynapse
# create the role if needed:
psql -d postgres -c "CREATE USER worksynapse_user WITH PASSWORD 'yourpassword' CREATEDB;"
psql -d postgres -c "GRANT ALL PRIVILEGES ON DATABASE worksynapse TO worksynapse_user;"

Make sure POSTGRES_HOST=localhost in your .env (the Docker path uses db). Kafka is optional — the app logs a warning and keeps running if it's absent.

2. Backend API

cd backend

# Virtual environment
python -m venv venv
source venv/bin/activate            # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Apply database migrations
alembic upgrade head

# Seed roles/permissions and create an admin (run from backend/)
python manage.py init
python manage.py create_admin \
  --email admin@worksynapse.com --username admin \
  --password 'SecurePass123!' --superuser

# Run the dev server (auto-reload)
uvicorn app.main:app --reload --port 8000

API is now on http://localhost:8000 (docs at /api/v1/docs when DEBUG=true).

3. Celery worker + beat (optional — background jobs & AI agents)

In separate terminals, from backend/ with the venv active:

celery -A app.core.celery_app worker --loglevel=info
celery -A app.core.celery_app beat --loglevel=info

4. Web App (React + Vite)

cd web

# Frontend env — point it at your backend
cp .env.example .env.local
# ensure: VITE_API_URL=http://localhost:8000/api/v1

npm install
npm run dev

The dev server runs on http://localhost:5173.

⚠️ web/vite.config.ts ships with a hardcoded proxy target (http://10.0.101.117:8000). For local dev, change that target to http://localhost:8000 (or rely on VITE_API_URL).

5. Desktop App (Electron — optional, time tracking)

cd desktop
npm install
npm start

🏢 Multi-Tenancy Setup (Database-per-Tenant)

WorkSynapse supports database-per-tenant isolation: each organization gets its own PostgreSQL database, with a small master database holding the tenant registry. It is off by default (single-database mode) so everything above works unchanged.

To enable it:

# in .env
MULTI_TENANT_ENABLED=True
MASTER_POSTGRES_DB=worksynapse_master
TENANT_DB_PREFIX=worksynapse_tenant_
BASE_DOMAIN=worksynapse.com

The POSTGRES_USER must have the CREATEDB privilege. Then provision tenants (manual/admin — via CLI or the platform-admin API):

# CLI (from backend/, or `docker compose exec backend ...`)
python -m app.commands.provision_tenant create --name "Acme Corp" --slug acme
python -m app.commands.provision_tenant list

# API (protected by the service API key)
curl -X POST http://localhost:8000/api/v1/tenants \
  -H "X-API-Key: $SERVICE_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "slug": "acme", "plan": "PROFESSIONAL"}'

Requests are then routed to the right tenant DB by subdomain (acme.worksynapse.com), the X-Tenant-ID header, or the tenant JWT claim. Full details: backend/docs/MULTI_TENANCY.md.

✅ Verify the Setup

# Backend health (should return {"status": "healthy", ...})
curl http://localhost:8000/health

# Run the backend test suite (from backend/, venv active)
cd backend && pytest

📡 API Endpoints

Authentication

Method Endpoint Description
POST /api/v1/auth/login User login
POST /api/v1/auth/register User registration
POST /api/v1/auth/refresh Refresh tokens
POST /api/v1/auth/logout User logout

Tenants (platform admin — X-API-Key required)

Method Endpoint Description
POST /api/v1/tenants Provision a tenant (creates its database)
GET /api/v1/tenants List all tenants
GET /api/v1/tenants/{slug} Get a tenant
DELETE /api/v1/tenants/{slug} Deprovision a tenant (drops its database)

Users

Method Endpoint Description
GET /api/v1/users List users
GET /api/v1/users/{id} Get user
PUT /api/v1/users/{id} Update user

Projects

Method Endpoint Description
GET /api/v1/projects List projects
POST /api/v1/projects Create project
GET /api/v1/projects/{id} Get project
PUT /api/v1/projects/{id} Update project
DELETE /api/v1/projects/{id} Delete project

Tasks

Method Endpoint Description
GET /api/v1/tasks List tasks (filter: project_id, assignee_id, section_id, status)
POST /api/v1/tasks Create task
GET /api/v1/tasks/{id} Get task
PATCH /api/v1/tasks/{id} Update task (partial)
DELETE /api/v1/tasks/{id} Delete task

🗂️ Asana-Parity Work Management

WorkSynapse ships a full Asana-style work-management API. Everything below is tenant-aware (routed to the caller's tenant database) and available to every new tenant automatically.

Task collaboration (/api/v1/tasks/...)

Method Endpoint Description
GET/POST /{id}/comments List / add comments (parses @username mentions)
GET/POST /{id}/followers List / add followers (collaborators)
DELETE /{id}/followers/{user_id} Remove a follower
PUT/GET/DELETE /{id}/recurrence Set / get / clear a recurring rule
PUT/GET /{id}/custom-fields Set / list custom-field values on a task

Sections, Custom Fields & Views (/api/v1/tasks/...)

Method Endpoint Description
POST/GET /sections (?project_id=) Create / list project sections
PATCH/DELETE /sections/{id} Update / delete a section
POST/GET /custom-fields Create / list typed custom field definitions
PATCH/DELETE /custom-fields/{id} Update / delete a custom field
GET /views/list?project_id= List view — tasks grouped by section
GET /views/calendar?project_id=&start=&end= Calendar view (by due date)
GET /views/timeline?project_id= Timeline / Gantt view (dates + dependencies)

Portfolios (/api/v1/portfolios)

Method Endpoint Description
POST/GET / Create / list portfolios
GET /{id} Get portfolio (with rolled-up progress %)
PATCH/DELETE /{id} Update / delete
POST/DELETE /{id}/projects/{project_id} Add / remove a project
POST/GET /{id}/status Post / list status updates

Goals / OKRs (/api/v1/goals)

Method Endpoint Description
POST/GET / Create / list goals (auto progress_percent)
GET/PATCH/DELETE /{id} Get / update / delete
POST/GET /{id}/status Post / list status updates

Workload (/api/v1/workload)

Method Endpoint Description
GET /?project_id=&capacity_minutes=&start=&end= Per-assignee capacity, flags over-capacity

Forms (/api/v1/forms)

Method Endpoint Description
POST/GET / (?project_id=) Create / list intake forms
GET/PATCH/DELETE /{id} Get / update / delete
POST /{id}/submit Submit — creates a task from the submission

Automation Rules (/api/v1/automation)

Method Endpoint Description
POST/GET /rules (?project_id=) Create / list rules
GET/PATCH/DELETE /rules/{id} Get / update / delete

Rules run automatically on task create/update. Triggers: TASK_CREATED, TASK_UPDATED, TASK_STATUS_CHANGED, TASK_COMPLETED, TASK_ASSIGNED, TASK_MOVED_SECTION. Actions: set status/priority/assignee, move section, add follower/comment, set due date.

Templates (/api/v1/templates)

Method Endpoint Description
POST/GET / (?template_type=) Create / list project/task templates
GET/DELETE /{id} Get / delete
POST /{id}/instantiate Apply a template to a project (creates sections + tasks)

Approvals (/api/v1/approvals)

Method Endpoint Description
POST / Request approval on a task
GET /?task_id= List a task's approvals
POST /{id}/decision Approve / reject / request changes

Inbox / Notifications (/api/v1/inbox)

Method Endpoint Description
GET / (?unread_only=) The user's notification feed
GET /unread-count Unread count
POST /read-all Mark all read
POST /{id}/read Mark one read
DELETE /{id} Delete a notification

Notifications fire automatically on: task assignment, @mention in a comment, comments on followed/assigned tasks, and approval requests/decisions.

WebSocket

Endpoint Description
WS /api/v1/ws/{channel_id}?token=XXX Real-time chat

Webhooks

Method Endpoint Description
POST /api/v1/webhooks/github GitHub events
POST /api/v1/webhooks/jira Jira events

Health

Method Endpoint Description
GET /health Health check
GET /metrics Prometheus metrics

🤖 AI Agents

Project Manager Agent

# Capabilities
- Create project roadmaps
- Generate milestones
- Track progress
- Suggest timeline adjustments

Task Generator Agent

# Capabilities
- Convert features to tasks
- Estimate story points
- Create subtasks
- Generate acceptance criteria

Dev Assistant Agent

# Capabilities
- Answer code questions
- Explain complex logic
- Suggest bug fixes
- Code review assistance

Productivity Agent

# Capabilities
- Analyze work patterns
- Generate productivity reports
- Identify bottlenecks
- Suggest improvements

☸️ Kubernetes Deployment

# Create namespace
kubectl apply -f devops/k8s/config-secrets.yaml

# Deploy databases
kubectl apply -f devops/k8s/database-deployment.yaml

# Deploy backend
kubectl apply -f devops/k8s/backend-deployment.yaml

# Deploy workers
kubectl apply -f devops/k8s/celery-deployment.yaml

# Deploy frontend & ingress
kubectl apply -f devops/k8s/web-ingress.yaml

📊 Environment Variables

Variable Description Required
SECRET_KEY JWT signing key (min 32 chars) ✅
SERVICE_API_KEY Service-to-service auth ✅
POSTGRES_USER Database username ✅
POSTGRES_PASSWORD Database password ✅
REDIS_PASSWORD Redis password ✅
RABBITMQ_PASSWORD RabbitMQ password ✅
OPENAI_API_KEY OpenAI for AI agents ⚡
GITHUB_WEBHOOK_SECRET GitHub webhook secret ⚡
DEBUG Enables API docs (/api/v1/docs) when true ⚡
MULTI_TENANT_ENABLED Turn on database-per-tenant routing ⚡
MASTER_POSTGRES_DB Control-plane DB name (multi-tenant) ⚡
TENANT_DB_PREFIX Prefix for tenant database names ⚡
BASE_DOMAIN Domain used to derive tenant slug from subdomain ⚡

See .env.example for full list. Multi-tenancy details: backend/docs/MULTI_TENANCY.md.

🤝 Contributing

  1. Fork the repository
  2. Create feature branch (git checkout -b feature/amazing-feature)
  3. Commit changes (git commit -m 'Add amazing feature')
  4. Push to branch (git push origin feature/amazing-feature)
  5. Open Pull Request

📄 License

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

Built with ❤️ for Enterprise Teams

Website • Documentation • Report Bug