🏢 ORG-OS

Your Organizational Operating System

A modern, visual platform for team management, role organization, and workflow orchestration.

📖 Overview

ORG-OS is a comprehensive organizational management platform that helps teams visualize, structure, and manage their operations through an intuitive interface. Built on the T3 Stack, it combines type safety, performance, and developer experience with powerful visual tools for organizational design.

Key Highlights

🎨 Visual Team Canvas - Drag-and-drop interface for creating and organizing team roles using React Flow
🔄 Workflow Builder - Design and execute custom workflows with visual node-based editor
📊 Metrics Dashboard - Track KPIs and performance indicators across roles and teams
🔐 Enterprise Authentication - WorkOS-powered auth with organization support
🌐 Multi-tenant Architecture - Full organization isolation and access control
📱 Modern UI/UX - Beautiful, responsive design with shadcn/ui components

✨ Features

Team Management System

Visual Team Canvas: Create organizational structures with an interactive React Flow canvas
Role Management: Define roles with purposes, metrics, and user assignments
Dynamic Connections: Link roles to show reporting relationships and workflows
Real-time Sync: Auto-save canvas changes with optimistic updates
Color Coding: Visual organization with customizable role colors

Workflow Builder

Visual Workflow Editor: Build complex workflows using drag-and-drop nodes
Multiple Node Types: Initial, Transform, Branch, Join, and Output nodes
Auto Layout: ELK.js-powered automatic graph layout
Workflow Execution: Run workflows with visual execution feedback
Custom Edges: Interactive edge buttons for adding/removing connections

Metrics & Analytics

KPI Tracking: Define and track organizational metrics
Multiple Metric Types: Percentage, number, duration, and rate metrics
Role Association: Link metrics to specific roles
Mock Data Generation: AI-powered mock data for testing and demos
Performance Monitoring: Track current vs target values

Integration Platform

Nango Integration: OAuth-based connections to external services
Webhook Support: Real-time sync with external platforms
API Management: Manage integrations through intuitive UI

Documentation System

MDX-Powered Docs: Interactive documentation with live code examples
Mermaid Diagrams: Visual architecture and flow diagrams
Live Code Snippets: Syntax-highlighted code with copy functionality
Architecture Guides: Comprehensive guides on concepts and patterns

🛠️ Tech Stack

Core Framework

Next.js 15.5 - React framework with App Router and Server Components
React 19 - Latest React with concurrent features
TypeScript 5.9 - Full type safety across the stack

Backend

tRPC 11 - End-to-end typesafe APIs without code generation
Prisma 6 - Type-safe ORM with PostgreSQL
Zod - Runtime type validation

Frontend & UI

Tailwind CSS 4 - Utility-first CSS framework
shadcn/ui - High-quality component library
Radix UI - Accessible component primitives
Lucide Icons - Beautiful & consistent icons

Data Fetching & State

TanStack Query 5 - Powerful data fetching and caching
Zustand - Lightweight state management
React Hook Form - Performant form handling

Visualization & Animation

React Flow - Node-based workflow and diagram builder
ELK.js - Automatic graph layout
GSAP - Professional-grade animations
Mermaid - Diagram and flowchart generation

Authentication & Authorization

WorkOS AuthKit - Enterprise-grade authentication
Iron Session - Secure session management

Integrations

Nango - OAuth and API integration platform

Developer Experience

ESLint 9 - Code linting with TypeScript support
Prettier - Code formatting
Husky - Git hooks
Playwright - End-to-end testing

Documentation

MDX - Markdown with JSX components
Rehype - HTML processor for rich code blocks
Shiki - Syntax highlighting

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Node.js 18+ (Download)
pnpm 9+ (Install via npm install -g pnpm)
PostgreSQL 14+ (Download)
WorkOS Account (Sign up)

Installation

1. Clone the Repository

git clone https://github.com/drifter089/orgOS.git
cd orgOS

2. Install Dependencies

pnpm install

3. Set Up Environment Variables

Copy the example environment file:

cp .env.example .env

Edit .env and configure the following variables:

Database Configuration

# PostgreSQL connection string
# Format: postgresql://username:password@host:port/database
DATABASE_URL="postgresql://postgres:password@localhost:5432/org_os"

WorkOS Authentication (Required)

Create a WorkOS account and get your credentials:

Sign up at workos.com
Create a new application
Get your API key and Client ID from the dashboard

# WorkOS API Key (starts with sk_test_ or sk_live_)
WORKOS_API_KEY="sk_test_..."

# WorkOS Client ID (starts with client_)
WORKOS_CLIENT_ID="client_..."

# Cookie encryption key (generate with: openssl rand -base64 32)
WORKOS_COOKIE_PASSWORD="your-32-character-secret-key-here"

# OAuth redirect URI (must match WorkOS dashboard settings)
NEXT_PUBLIC_WORKOS_REDIRECT_URI="http://localhost:3000/api/callback"

Nango Integration Platform (Optional)

For OAuth integrations with external services:

Sign up at nango.dev
Get your secret key from Environment Settings

# Nango Secret Key
NANGO_SECRET_KEY_DEV="nango_secret_key_..."

# Nango Webhook Secret (optional, for production)
# NANGO_WEBHOOK_SECRET="your_webhook_secret_here"

Test User Credentials (For Testing)

Create a test user in WorkOS Dashboard and add credentials:

TEST_USER_EMAIL="test-user@example.com"
TEST_USER_PASSWORD="test-password"

WorkOS Directory Sync (Optional)

Only needed for SSO-based organizations:

# WORKOS_DIR_ID="directory_..."

4. Set Up the Database

Generate Prisma client and push schema to database:

# Generate Prisma client
pnpm db:generate

# Push schema to database (development)
pnpm db:push

# Or run migrations (production)
pnpm db:migrate

5. Seed the Database (Optional)

Populate with sample metrics:

pnpm db:seed

6. Start the Development Server

pnpm dev

The application will be available at http://localhost:3000

📦 Development Workflow

Available Commands

Development

pnpm dev              # Start development server with Turbo
pnpm build            # Build for production
pnpm start            # Start production server
pnpm preview          # Build and preview production

Code Quality

pnpm check            # Run lint + typecheck together
pnpm lint             # Run ESLint
pnpm lint:fix         # Auto-fix ESLint issues
pnpm typecheck        # Run TypeScript checks
pnpm format:check     # Check code formatting
pnpm format:write     # Format code with Prettier

Database

pnpm db:generate      # Generate Prisma client
pnpm db:push          # Push schema changes (dev)
pnpm db:migrate       # Deploy migrations (prod)
pnpm db:studio        # Open Prisma Studio GUI
pnpm db:seed          # Seed sample data

Testing

# Run all tests
pnpm exec playwright test

# Run specific test file
pnpm exec playwright test tests/auth-authenticated.spec.ts

# Run in specific browser
pnpm exec playwright test --project=chromium

# Interactive UI mode
pnpm exec playwright test --ui

# Debug mode
pnpm exec playwright test --debug

# View test report
pnpm exec playwright show-report

# Generate test code
pnpm exec playwright codegen

Documentation

pnpm sync:docs        # Validate documentation
pnpm sync:docs:fix    # Auto-fix version numbers
pnpm ai-sync:docs     # AI-powered doc sync

Git Workflow

The project uses Husky for git hooks:

Pre-commit: Auto-format and lint staged files
Commit: Validates commit messages
Pre-push: Runs type checks

📂 Project Structure

orgOS/
├── prisma/
│   ├── schema.prisma          # Database schema
│   └── seed.ts                # Database seeding
├── public/                    # Static assets
├── scripts/                   # Build and sync scripts
├── src/
│   ├── app/                   # Next.js app directory
│   │   ├── api/              # API routes (WorkOS callbacks)
│   │   ├── docs/             # MDX documentation
│   │   ├── teams/            # Team management pages
│   │   │   └── [teamId]/    # Team canvas & role management
│   │   ├── workflow/         # Visual workflow builder
│   │   ├── metric/           # Metrics dashboard
│   │   ├── org/              # Organization settings
│   │   └── layout.tsx        # Root layout
│   ├── components/           # Shared React components
│   │   ├── ui/              # shadcn/ui components
│   │   └── navbar/          # Navigation components
│   ├── hooks/                # Custom React hooks
│   ├── lib/                  # Utility functions
│   ├── providers/            # React context providers
│   ├── server/               # Server-side code
│   │   ├── api/             # tRPC routers
│   │   └── db.ts            # Prisma client
│   ├── styles/               # Global styles
│   ├── trpc/                 # tRPC client setup
│   ├── env.js                # Environment validation
│   └── middleware.ts         # Auth middleware
├── tests/                     # E2E tests
├── .env.example              # Environment template
├── CLAUDE.md                 # AI assistant guide
└── README.md                 # This file

Key Directories

src/app/teams/[teamId]/: Team canvas with React Flow integration
- _components/: Role nodes, edges, dialogs
- store/: Zustand state management
- hooks/: Auto-save and layout hooks
- utils/: Canvas serialization utilities
src/app/workflow/: Visual workflow builder
- components/nodes/: Node type implementations
- components/edges/: Edge components with buttons
- hooks/: Layout and execution logic
- store/: Workflow state management
src/server/api/routers/: tRPC API routes
- team.ts: Team CRUD operations
- role.ts: Role management
- metric.ts: Metrics and KPIs
- integration.ts: Nango integrations

🧪 Testing

End-to-End Testing with Playwright

The project uses Playwright for comprehensive E2E testing:

Test Setup

Ensure test user is created in WorkOS Dashboard
Add credentials to .env:

TEST_USER_EMAIL="test-user@example.com"
TEST_USER_PASSWORD="test-password"

Running Tests

# Run all tests
pnpm exec playwright test

# Run with UI
pnpm exec playwright test --ui

# Run specific test
pnpm exec playwright test tests/auth-authenticated.spec.ts

# Debug tests
pnpm exec playwright test --debug

Test Files

tests/auth-authenticated.spec.ts: Authenticated user flows
tests/global-setup.ts: Authentication setup
tests/fixtures/: Custom test fixtures

📚 Documentation

In-App Documentation

Visit /docs in the running application for comprehensive documentation:

Architecture Concepts: Server/Client components, TanStack Query, tRPC patterns
Integration Patterns: Server prefetching, cache strategies, auth flow
Changelog: Feature updates and changes
Roadmap: Planned features and improvements

Key Documentation Files

CLAUDE.md: Developer guidance for AI assistants
README.md: This file
scripts/README.md: Documentation sync system guide

🏗️ Architecture

Authentication Flow

User Request → Next.js Middleware → WorkOS AuthKit
    ↓
Protected Routes → tRPC Context → Protected Procedures
    ↓
Organization Validation → Database Query → Response

Data Flow

Server Component → tRPC Server Caller (direct)
    ↓
Prefetch Data → Dehydrate State → Client
    ↓
Client Component → TanStack Query → Background Refetch

Multi-Tenancy

Organization-based isolation via WorkOS
All queries filtered by organization ID
Helper utilities for access control
Team-level permissions

🎨 UI Components

Design System

Components: shadcn/ui with Radix UI primitives
Styling: Tailwind CSS 4 with custom design tokens
Icons: Lucide React for consistent iconography
Animations: GSAP for complex animations
Themes: Dark/Light mode with next-themes

Key UI Features

Responsive layouts with mobile support
Accessible components (WCAG compliant)
Toast notifications via Sonner
Dialog and modal systems
Form validation with Zod
Auto-complete and search

🔒 Security

Authentication: WorkOS enterprise auth with MFA support
Authorization: Organization-based access control
Session Management: Encrypted iron-session cookies
Input Validation: Zod schemas on client and server
SQL Injection: Protected via Prisma ORM
XSS Protection: React's built-in sanitization
CSRF: SameSite cookie policies

🌐 Deployment

Vercel (Recommended)

Push code to GitHub
Import project in Vercel
Add environment variables
Deploy

Docker

# Build image
docker build -t org-os .

# Run container
docker run -p 3000:3000 --env-file .env org-os

Environment Checklist

✅ Set DATABASE_URL to production database
✅ Configure WorkOS production keys
✅ Set secure WORKOS_COOKIE_PASSWORD
✅ Update NEXT_PUBLIC_WORKOS_REDIRECT_URI
✅ Configure Nango production keys (if using)
✅ Set up database migrations

🤝 Contributing

We welcome contributions! Here's how to get started:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests and linting (pnpm check)
Commit your changes (git commit -m 'Add amazing feature')
Push to your branch (git push origin feature/amazing-feature)
Open a Pull Request

Contribution Guidelines

Follow the existing code style
Write meaningful commit messages
Add tests for new features
Update documentation as needed
Ensure all checks pass

🐛 Troubleshooting

Common Issues

Database connection fails

# Check PostgreSQL is running
sudo service postgresql status

# Verify DATABASE_URL format
postgresql://username:password@host:port/database

WorkOS authentication errors

Verify API keys in .env
Check redirect URI matches WorkOS dashboard
Ensure cookie password is set

Build errors

# Clear cache and reinstall
rm -rf node_modules .next
pnpm install
pnpm build

Prisma errors

# Regenerate Prisma client
pnpm db:generate

# Reset database (⚠️ destroys data)
pnpm prisma migrate reset

📄 License

This project is open source and available under the MIT License.

🙏 Acknowledgments

T3 Stack for the amazing foundation
shadcn for the beautiful UI components
WorkOS for enterprise authentication
Vercel for hosting and deployment
All our contributors and supporters

📞 Support & Links

GitHub: github.com/drifter089/orgOS
Issues: Report a bug
Discussions: Join the conversation

Built with ❤️ using the T3 Stack

T3 Stack • Next.js • tRPC • Prisma

Name		Name	Last commit message	Last commit date
Latest commit History 802 Commits
.claude		.claude
.github/workflows		.github/workflows
.husky		.husky
dev/scripts		dev/scripts
prisma		prisma
public		public
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.mcp.json		.mcp.json
.npmrc		.npmrc
.prettierignore		.prettierignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CLEANUP_PLAN.md		CLEANUP_PLAN.md
GEMINI.md		GEMINI.md
README.md		README.md
ROADMAP.md		ROADMAP.md
components.json		components.json
eslint.config.js		eslint.config.js
mdx-components.tsx		mdx-components.tsx
next.config.js		next.config.js
package.json		package.json
playwright.config.ts		playwright.config.ts
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.js		postcss.config.js
prettier.config.js		prettier.config.js
start-database.sh		start-database.sh
tsconfig.json		tsconfig.json
vercel.json		vercel.json

drifter089/orgOS

Folders and files

Latest commit

History

Repository files navigation

🏢 ORG-OS

📖 Overview

Key Highlights

✨ Features

Team Management System

Workflow Builder

Metrics & Analytics

Integration Platform

Documentation System

🛠️ Tech Stack

Core Framework

Backend

Frontend & UI

Data Fetching & State

Visualization & Animation

Authentication & Authorization

Integrations

Developer Experience

Documentation

🚀 Getting Started

Prerequisites

Installation

1. Clone the Repository

2. Install Dependencies

3. Set Up Environment Variables

Database Configuration

WorkOS Authentication (Required)

Nango Integration Platform (Optional)

Test User Credentials (For Testing)

WorkOS Directory Sync (Optional)

4. Set Up the Database

5. Seed the Database (Optional)

6. Start the Development Server

📦 Development Workflow

Available Commands

Development

Code Quality

Database

Testing

Documentation

Git Workflow

📂 Project Structure

Key Directories

🧪 Testing

End-to-End Testing with Playwright

Test Setup

Running Tests

Test Files

📚 Documentation

In-App Documentation

Key Documentation Files

🏗️ Architecture

Authentication Flow

Data Flow

Multi-Tenancy

🎨 UI Components

Design System

Key UI Features

🔒 Security

🌐 Deployment

Vercel (Recommended)

Docker

Environment Checklist

🤝 Contributing

Contribution Guidelines

🐛 Troubleshooting

Common Issues

📄 License

🙏 Acknowledgments

📞 Support & Links

About

Resources

Uh oh!

Stars

Watchers

Packages