🧠 WorkSynapse

AI-Powered Intelligent Company Operating System

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

🎯 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
⏱️ 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
POST	`/api/v1/tasks`	Create task
GET	`/api/v1/tasks/{id}`	Get task
PUT	`/api/v1/tasks/{id}`	Update task
DELETE	`/api/v1/tasks/{id}`	Delete task

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

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
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

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
.github/workflows		.github/workflows
assets		assets
backend		backend
desktop		desktop
devops		devops
shared-types/models		shared-types/models
web		web
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
WorkSynapse.md		WorkSynapse.md
docker-compose.yml		docker-compose.yml
verify_startup.py		verify_startup.py

Folders and files

Latest commit

History

Repository files navigation