🚀 Fairlx - Enterprise-Grade Agile Project Management Platform

Production-Ready Agile Management for Modern Teams

Enterprise project management with organizations, workspaces, spaces, custom workflows, AI assistance, usage-based billing, and GitHub integration.

📖 Documentation | 🚀 Quick Start | 💡 Contributing | 🏗️ Architecture

</div>

📚 Table of Contents

Overview
Documentation
Key Features
Tech Stack
Quick Start Guide
Architecture & Data Flow
Project Structure
Environment Configuration
Feature Modules
Permission & RBAC System
Billing & Usage Tracking
AI Features
Development Workflow
Testing
Deployment
Contributing
Security

🎯 Overview

Fairlx is a production-ready enterprise project management platform built with Next.js 15, TypeScript, and Appwrite. It combines modern agile methodologies with powerful features for teams of any size.

What Makes Fairlx Different?

Dual Account System: Personal accounts for solo developers; Organization accounts with shared billing and multi-user management
Hierarchical Organization: Organiz ations → Workspaces → Spaces → Projects → Tasks (flexible 5-level structure)
Custom Workflows + AI: Build custom status flows and transitions with AI-powered suggestions and validation
Production Billing: Usage-based metering (traffic, storage, compute) with Razorpay integration, grace periods, and automated suspension
Enterprise RBAC: Multi-level role-based access control with granular permissions at org, workspace, space, project, and team levels
AI-First Features: Google Gemini integration for workflow assistance, code analysis, documentation generation
GitHub Native: Repository linking with automatic documentation generation and commit synchronization

Core Capabilities

| Capability | Implementation | |------------|----------------| | Account Types | Personal (individual use) and Organization (team collaboration with shared billing) | | Organization | Multi-tenant with departments, audit logs, role hierarchy (Owner/Admin/Moderator/Member) | | Workspaces | Multiple workspaces per account with Simple/Advanced UI modes and feature toggles | | Spaces | Logical containers (departments, products, clients) with unique keys for work item prefixing | | Projects | Scrum/Kanban/Hybrid boards with WIP limits, sprint management, GitHub integration | | Work Items | Tasks, Stories, Bugs, Epics with custom fields, labels, assignments, dependencies | | Workflows | Custom statuses and transitions with team-based rules and AI assistance | | Time Tracking | Estimates vs actuals, timesheets, variance analysis, capacity planning | | Billing | Usage metering, invoicing, Razorpay e-mandate, grace periods, account suspension | | AI Integration | Workflow suggestions, code Q&A, documentation generation via Gemini API |

📚 Documentation

| Document | Purpose | |----------|---------| | README.md | Complete setup, architecture, and feature reference (this file) | | CONTRIBUTING.md | Development guidelines, branching strategy, PR workflow | | CODE_OF_CONDUCT.md | Community standards and enforcement policies | | changelog.md | Detailed version history and implementation updates | | DATABASE_UPDATES.md | Schema changes, migrations, and workflow redesign notes | | PROGRAMS_IMPLEMENTATION_GUIDE.md | Complete guide to Programs feature architecture | | md/APPWRITE_SETUP.md | Step-by-step Appwrite database configuration | | md/APPWRITE_GUIDE.md | Complete collection schemas, attributes, and indexes | | md/MIGRATION_SETUP.md | Migration scripts for project RBAC and teams | | docs/FEATURES_COMPLETE.md | Implementation summary with performance improvements | | docs/SPACES_GUIDE.md | Visual guide to Spaces feature with use cases | | docs/SPACES_TESTING_GUIDE.md | Testing procedures for Spaces functionality | | docs/APPWRITE_ORGANIZATIONS_SETUP.md | Organization-level Appwrite configuration | | src/features/billing/VALIDATION_CHECKLIST.md | Pre-production billing system validation |

✨ Key Features

🏢 Organization & Workspace Management

Personal Accounts: For individual developers and freelancers
Organization Accounts: Team collaboration with shared billing and member management
Multi-Workspace: Create unlimited workspaces per account
UI Modes: Simple mode (small teams) or Advanced mode (enterprise features)
Feature Toggles: Enable/disable Spaces, Programs, Teams, Advanced Permissions per workspace
Departments: Organize organization members into departments with permissions

📋 Work Management

Work Items: Tasks, Stories, Bugs, Epics, Ideas, Improvements with rich metadata
Subtasks: Hierarchical task breakdown with progress tracking
Custom Fields: Text, number, date, select, multi-select, user, checkbox, URL, currency, percentage, labels
Work Item Links: Blocks, relates-to, duplicates, split-from, cloned-from, parent/child, causes relationships
Personal Backlog: Individual work queues independent of projects
Saved Views: Custom filters and sorting for Kanban, List, Calendar, Timeline views

🏃 Sprint & Board Management

Board Types: Scrum, Kanban, or Hybrid workflows
Sprint States: Planned, Active, Completed, Cancelled with velocity tracking
WIP Limits: Configure work-in-progress limits per column
Burndown Charts: Sprint progress visualization
Velocity Tracking: Team capacity and historical velocity analysis
Custom Columns: Configurable kanban columns with icons and colors

🔄 Workflows & Customization

Custom Workflows: Define status flows per workspace, space, or project
Status Types: Open, In Progress, Closed for analytics
Transitions: Controlled state changes with conditions
Team-Based Rules: Restrict transitions by team or role
Approval Workflows: Require approvals for specific transitions
Auto-Transitions: Automatic state changes based on conditions
AI Assistant: Generate workflows, suggest statuses/transitions, identify issues

⏱️ Time Tracking & Planning

Time Logs: Track actual time spent on tasks
Estimates: Story points and time estimates
Variance Analysis: Compare estimates vs actuals
Timesheets: Export time logs for reporting
Capacity Planning: Team capacity vs workload analysis
Timeline View: Gantt-style project timelines with epic grouping

👥 Team & Permission Management

Project Teams: Teams scoped to specific projects
Team Roles: Lead, Member, Custom roles with granular permissions
Project Members: Project-specific membership and roles
Custom Roles: Define custom role permissions per project
Organization Roles: Owner, Admin, Moderator, Member hierarchy
Workspace Roles: Admin, Editor, Viewer permissions
Space Roles: Admin/Master, Member, Viewer access levels

📎 Collaboration & Documentation

Comments: Threaded conversations with @mentions
Attachments: File uploads (20MB limit) with preview support
Project Documents: PRDs, FRDs, Technical Specs, API Docs (5GB storage)
AI Documentation: Auto-generate documentation from project context
Notifications: Real-time updates for assignments, status changes, comments
Audit Logs: Organization-level activity tracking

🐙 GitHub Integration

Repository Linking: Connect GitHub repos to projects
Commit Sync: Track commits and link to work items
AI Code Documentation: Auto-generate code documentation from repositories
Code Q&A: Ask questions about codebase with AI assistance
File References: Deep linking to specific files and lines

💳 Billing & Usage Tracking

Usage Metering: Track traffic (GB), storage (GB/month), compute units
Automated Billing: Monthly billing cycles with Razorpay integration
E-Mandate: Automatic payment collection via Razorpay e-mandate
Grace Periods: 14-day grace period before account suspension
Account Suspension: Automatic suspension for non-payment
Invoicing: Generated invoices with detailed usage breakdown
Wallet System: Prepaid wallet for billing (optional)
Multi-Currency: Support for different currencies

🤖 AI-Powered Features

Workflow AI: Analyze workflows, suggest improvements, generate templates
Code Analysis: Ask questions about linked

Fairlx

Install / Use

README