Teader Platform Documentation

What is Teader?

Teader is an AI-native, high-velocity project management platform engineered specifically for software engineering teams and autonomous AI coding agents. Unlike conventional ticketing systems, Teader delivers 0ms perceived UI latency through optimistic mutations, in-memory client caches, and instant visual feedback.

It combines the fluidity of modern issue boards with deep developer workflows: Unity VCS-style branch dependency graphs, infinite recursive task trees, developer workstation Git generators, and live Markdown technical specifications.

Quick Start Guide

Getting started with Teader takes less than two minutes. Follow this step-by-step sequence to clone, configure, seed, and launch your local instance:

# 1. Clone the repository
git clone https://github.com/ajaysaagar-dev/teader.git
cd teader/teader-web

# 2. Install dependencies
npm install

# 3. Configure environment variables
cp .env.example .env

# 4. Initialize database schema & demo records
npm run db:setup

# 5. Start development server with Turbopack
npm run dev

Once running, visit http://localhost:3000 in your browser.

System Requirements

Installation & Setup

Generate a cryptographically secure 64-byte random secret for JWT token signing before starting the server:

node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

Paste the resulting string into your .env file under the JWT_SECRET key.

Demo Credentials

When you run npm run db:setup, the database seeds the following sample accounts for immediate testing:

Authentication Architecture

Teader enforces enterprise-grade security primitives across all endpoints. Authentication is entirely stateless and handled via JSON Web Tokens signed with HMAC-SHA256, sealed inside secure, SameSite cookies.

JWT & HttpOnly Cookies

Upon successful login via /api/auth/login, the server responds with a signed cookie named teader_session configured with:

• HttpOnly: true — Immune to client-side XSS cookie extraction.
• SameSite: Lax — Protects against Cross-Site Request Forgery (CSRF).
• Max-Age: 7 Days — Persistent session validity with seamless refresh.

Password Hashing & Bcrypt

All user passwords are encrypted using Bcrypt with a work factor of 12 rounds. During authentication, legacy SHA-256 password records are transparently migrated to Bcrypt on first successful login without disrupting user sessions.

Rate Limiting Protection

To prevent brute-force credential stuffing, authentication routes employ an in-memory sliding window rate limiter:

Dashboard Overview

The Dashboard (/dashboard) is your operational command center. It aggregates real-time metrics across all active projects, highlighting urgent blockers, recent commits, personal assignments, and sprint velocity.

Sprint & Velocity Metrics

The dashboard automatically computes:

Workspace Navigation

Press ⌘K or Ctrl+K anywhere in the application to launch Quick Search and jump directly to any project, task key, or Markdown doc.

Creating a Project

To create a new workspace project, navigate to /projects and click + New Project. Provide a project name, description, and key prefix.

Project Keys & Unique IDs

Every project generates a unique uppercase key (e.g. TED, CORE, GRAPH). All child tasks inherit this key prefix followed by an auto-incrementing serial number (e.g., TED-104).

Joining via Project Key

Teammates can join any existing workspace without invitation links by entering the Project Key in the Join Project modal. Once verified, the project immediately appears on their dashboard.

Member Roles & Permissions

Encrypted Project Dumps (.teaderdumpfile)

Export an entire workspace including all tasks, subtask hierarchies, Markdown specs, and member mappings into an encrypted binary bundle with AES-256-GCM cipher and SHA-256 integrity checksums.

Board Columns & States

The Kanban Board organizes work across four progressive lifecycle states:

Drag & Drop Reordering

Cards support smooth drag-and-drop using hardware-accelerated pointer events. Moving a card immediately calculates the new sequence index and dispatches a bulk reorder payload to /api/issues/reorder in the background.

0ms Optimistic Mutations

When you drag a task between columns, the UI reparents the DOM element instantaneously (0ms lag). If a network failure occurs, the state engine rolls back to the cached snapshot and displays a notification.

Done-State Creator Protection

Unity VCS Graph Concept

The Branch Explorer is a visual version control timeline modeled after Unity Version Control (Plastic SCM). It plots branches as horizontal subway-style lines that diverge from the main branch and converge upon merge completion.

Cubic Bezier Spline Engine

Connections between parent tasks, child branches, and dependency nodes are drawn using SVG cubic Bezier curves (M x1 y1 C cx1 cy1, cx2 cy2, x2 y2) with ease-in-ease-out smoothing.

Drag-to-Pan & Scroll Controls

Navigate massive dependency graphs effortlessly:

• Click & Drag Canvas: Pan the graph horizontally and vertically.
• Trackpad Two-Finger Swipe: Smooth momentum panning.
• Pan Buttons: Dedicated left and right navigation buttons on the graph toolbar.

Developer Workstation Mode

Dev Stream transforms Teader into a focused workstation HUD for active coding. Selecting any task displays generated Git terminal commands, branch suggestions, and checklist steps.

Automated Git Command Generator

With a single click, copy standard Git commands formatted with the active task key and title slug:

# Generated for Task TED-104: Add OAuth2 Provider
git checkout -b feature/TED-104-add-oauth2-provider
git add .
git commit -m "feat(auth): implement oauth2 provider flow [TED-104]"
git push origin feature/TED-104-add-oauth2-provider

Live Technical Documentation

Teader features a built-in technical wiki for architecture specs, RFCs, and API documentation directly within each workspace.

Split-Screen Markdown Editor

Write in GitHub-flavored Markdown with support for code syntax highlighting, tables, task lists, and mathematical notation. Preview changes side-by-side in real time.

Instant Ctrl+S Persistence

Press Ctrl+S to persist changes immediately to PostgreSQL. A floating indicator confirms database synchronization status.

Server-Sent Events (SSE)

Teader establishes an HTTP persistent stream over /api/realtime/stream. Team updates dispatch event payloads including:

REST API & Endpoints

Teader provides a comprehensive REST API for automation, CI/CD pipelines, and autonomous AI agents to manage projects, tasks, comments, and real-time state.

Global Shortcuts Cheatsheet