Clonear

A feature-rich project management tool inspired by Linear

Features • Tech Stack • Getting Started • Environment • Development • Documentation

---

Features

Core Issue Management

• Issue Tracking - Create, edit, and manage issues with rich metadata
• Kanban Board - Drag-and-drop board view with status columns
• List View - Traditional list view with sorting and filtering
• Issue Relations - Link issues as blocking, blocked by, relates to, or duplicate
• Sub-issues - Create parent-child issue hierarchies
• Comments - Threaded comments with nested replies

Project Planning

• Projects - Organize work into projects with milestones and progress tracking
• Cycles - Time-boxed sprints with burndown tracking
• Initiatives - Group projects under strategic initiatives
• Project Documents - Rich text documents with auto-save (Google Docs-style)
• Timeline View - Gantt-style project timeline visualization

Team Collaboration

• Teams - Multi-team support with team-specific workflows
• Team Members - Invite and manage team members with roles (owner, admin, member)
• Asks - External request intake from Slack, email, or forms
• Activity Feed - Real-time activity tracking on issues

Analytics & Insights

• Metrics Dashboard - Issue count, effort, cycle time, lead time, triage time
• Time-Series Charts - Track trends over time with area and line charts
• Distribution Charts - Analyze by status, priority, assignee, project
• Custom Dashboards - Build personalized dashboards with widgets
• CSV Export - Export filtered data for external analysis

Integrations

• GitHub Integration - Link PRs and commits to issues
• Auto-progression - Automatically update issue status based on PR activity
• OAuth Authentication - Secure sign-in with GitHub

User Experience

• Dark/Light Theme - System-aware theme with manual override
• Keyboard Shortcuts - Full keyboard navigation (↑↓ navigate, Enter select, Esc close)
• Compact Mode - Dense view for power users
• Responsive Design - Works on desktop and mobile
• Real-time Updates - Optimistic UI with instant feedback

---

Tech Stack

Layer	Technology
Framework	Next.js 16 with App Router
Language	TypeScript
Styling	Tailwind CSS
Database	PostgreSQL
ORM	Drizzle ORM
Authentication	NextAuth.js with GitHub OAuth
State Management	Zustand
Charts	Recharts
Icons	Lucide React
Runtime	Bun

---

Getting Started

Prerequisites

• Bun >= 1.0 (or Node.js >= 18)
• Git
• PostgreSQL >= 14
• GitHub OAuth App (for authentication)

Installation

1. Clone the repository

   git clone https://github.com/ncklrs/clonear.git
   cd clonear

2. Install dependencies

   bun install

3. Set up environment variables

   cp .env.example .env.local

   Edit .env.local with your configuration (see Environment Variables)

4. Set up the database

   # Push schema to database
   bun run db:push
   
   # Seed with sample data (optional)
   bun run db:seed

5. Run the development server

   bun dev

6. Open your browser Navigate to http://localhost:3000

---

Environment Variables

Create a .env.local file in the root directory:

# Database (required)
DATABASE_URL=postgresql://user:password@localhost:5432/clonear

# Authentication (required for GitHub OAuth)
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-key-here-generate-with-openssl

# GitHub OAuth (optional - for authentication)
GITHUB_ID=your-github-oauth-app-id
GITHUB_SECRET=your-github-oauth-app-secret

# GitHub Integration (optional - for PR/commit linking)
GITHUB_APP_ID=your-github-app-id
GITHUB_PRIVATE_KEY=your-github-app-private-key
GITHUB_WEBHOOK_SECRET=your-webhook-secret

Generating Secrets

# Generate NEXTAUTH_SECRET
openssl rand -base64 32

Setting up PostgreSQL

# macOS with Homebrew
brew install postgresql@16
brew services start postgresql@16

# Create database
createdb clonear

# Or use Docker
docker run --name clonear-db -e POSTGRES_DB=clonear -e POSTGRES_PASSWORD=password -p 5432:5432 -d postgres:16

Setting up GitHub OAuth

1. Go to GitHub Developer Settings
2. Click "New OAuth App"
3. Fill in the details:
   • Application name: Clonear Local
   • Homepage URL: http://localhost:3000
   • Authorization callback URL: http://localhost:3000/api/auth/callback/github
4. Copy the Client ID and Client Secret to your .env.local

---

Development

Available Scripts

# Development server with hot reload
bun dev

# Production build
bun run build

# Start production server
bun start

# Lint code
bun run lint

# Database commands
bun run db:generate    # Generate migrations from schema changes
bun run db:migrate     # Run migrations
bun run db:push        # Push schema directly (dev)
bun run db:studio      # Open Drizzle Studio GUI
bun run db:seed        # Seed database with sample data

Project Structure

clonear/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── api/                # API routes
│   │   │   ├── issues/         # Issue CRUD
│   │   │   ├── projects/       # Projects & documents
│   │   │   ├── cycles/         # Sprint cycles
│   │   │   ├── insights/       # Analytics APIs
│   │   │   ├── dashboards/     # Custom dashboards
│   │   │   ├── asks/           # External requests
│   │   │   ├── github/         # GitHub integration
│   │   │   └── ...
│   │   ├── login/              # Login page
│   │   └── page.tsx            # Main app page
│   ├── components/             # React components
│   │   ├── issues/             # Issue list, detail, kanban
│   │   ├── projects/           # Projects view
│   │   ├── cycles/             # Cycles view
│   │   ├── insights/           # Analytics dashboard
│   │   ├── asks/               # Asks management
│   │   ├── settings/           # Settings panels
│   │   ├── layout/             # Sidebar, header
│   │   └── modals/             # Modal dialogs
│   ├── hooks/                  # Custom React hooks
│   ├── lib/                    # Utilities
│   │   ├── db/                 # Database setup & queries
│   │   │   ├── index.ts        # Drizzle client
│   │   │   ├── schema.ts       # Database schema
│   │   │   └── seed.ts         # Seed script
│   │   └── utils.ts            # Helper functions
│   ├── store/                  # Zustand state management
│   └── types/                  # TypeScript definitions
├── drizzle/                    # Database migrations
├── docs/                       # Documentation
├── public/                     # Static assets
├── drizzle.config.ts           # Drizzle Kit configuration
├── .env.example                # Environment template
└── package.json

Database Schema

Clonear uses PostgreSQL with Drizzle ORM for type-safe database access.

Core Tables:

• users - User accounts
• teams - Team workspaces
• team_members - Team membership with roles
• issues - Issue tracking
• issue_relations - Issue links (blocks, duplicates, etc.)
• issue_labels - Many-to-many issue-label links
• issue_status_history - Status change audit trail
• comments - Threaded issue comments
• activities - Activity feed entries

Project Planning:

• initiatives - Strategic initiatives
• projects - Project management
• project_documents - Rich text documents
• project_dependencies - Project relationships
• milestones - Project milestones
• cycles - Sprint cycles
• issue_counters - Auto-incrementing issue IDs

Analytics:

• dashboards - Custom dashboards
• dashboard_widgets - Dashboard widget configurations

Integrations:

• asks - External request intake
• ask_channels - Request sources
• ask_comments - Request comments
• github_repos - Connected GitHub repositories
• github_pull_requests - Linked PRs
• github_commits - Linked commits
• github_automations - Auto-progression rules

See docs/DATABASE.md for the complete schema reference.

API Routes

Endpoint	Methods	Description
/api/issues	GET, POST	List and create issues
/api/issues/[id]	GET, PATCH, DELETE	Issue CRUD
/api/issues/[id]/relations	GET, POST, DELETE	Issue relations
/api/projects	GET, POST	List and create projects
/api/projects/[id]/documents	GET, POST	Project documents
/api/cycles	GET, POST	List and create cycles
/api/insights/metrics	GET	Aggregate metrics
/api/insights/time-series	GET	Time-based chart data
/api/insights/distribution	GET	Grouped chart data
/api/insights/export	GET	CSV export
/api/dashboards	GET, POST	Custom dashboards
/api/asks	GET, POST	External requests
/api/github/repos	GET, POST	GitHub repositories

See docs/API.md for the complete API reference.

---

Keyboard Shortcuts

Shortcut	Action
↑ / ↓	Navigate issues
Enter	Select issue
Esc	Close panel/modal
c	Create new issue
⌘K / Ctrl+K	Open search

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

---

License

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

---

Acknowledgments

• Inspired by Linear - the tool that makes issue tracking enjoyable
• Built with Next.js and the amazing React ecosystem

---

Made with ❤️ by ncklrs