Project Structure

The kit follows Next.js App Router conventions with a clean separation between frontend components, backend logic, and database infrastructure.

Top-Level Structure

kanban-fullstack/
├── app/                    # Next.js routes
├── components/             # React components (3-tier hierarchy)
├── data/                   # Static data (seed.ts for fallback/demo)
├── hooks/                  # Custom React hooks
├── lib/                    # Utilities, Supabase clients, Server Actions
├── supabase/               # Database migrations and seed data
├── types/                  # TypeScript type definitions
├── public/                 # Static assets
├── middleware.ts           # Auth middleware for route protection
└── .env.example            # Environment variable template

Route Groups

The app/ directory uses Next.js route groups for layout separation:

app/
├── (auth)/                 # Authentication pages
│   ├── login/
│   ├── register/
│   ├── forgot-password/
│   └── auth/               # OAuth callback and email confirm routes
│       ├── callback/
│       └── confirm/
├── (dashboard)/            # Main PM application (protected)
│   ├── page.tsx            # Dashboard with KPI stats and activity feed
│   ├── projects/           # Project management
│   │   ├── page.tsx        # Project list
│   │   ├── new/            # Create project
│   │   └── [id]/           # Project detail
│   │       ├── page.tsx    # Project overview (redirects to default view)
│   │       ├── board/      # Kanban board view
│   │       ├── list/       # List view with grouping
│   │       ├── timeline/   # Gantt chart / timeline view
│   │       ├── calendar/   # Calendar view
│   │       ├── backlog/    # Backlog management
│   │       ├── cycles/     # Sprint cycles list
│   │       │   └── [cycleId]/  # Cycle detail with tasks
│   │       ├── modules/    # Module list
│   │       │   └── [moduleId]/ # Module detail with tasks
│   │       ├── pages/      # Wiki pages list
│   │       │   └── [pageId]/   # Page editor
│   │       ├── tasks/
│   │       │   └── [taskId]/   # Task detail view
│   │       ├── automations/    # Automation rules
│   │       ├── analytics/      # Project-level analytics
│   │       └── settings/       # Project settings
│   ├── my-work/            # Personal task queue
│   ├── goals/              # OKR tracking
│   ├── activity/           # Workspace activity feed
│   ├── inbox/              # Notification inbox
│   ├── analytics/          # Workspace-level analytics
│   ├── roadmap/            # Cross-project roadmap
│   ├── workload/           # Team workload visualization
│   ├── views/              # Saved custom views
│   ├── templates/          # Project templates
│   ├── search/             # Global search
│   ├── team/               # Team management
│   │   ├── page.tsx        # Team member list
│   │   └── [id]/           # Member detail
│   └── settings/           # Workspace settings
│       ├── page.tsx        # General settings
│       ├── members/        # Member management
│       ├── labels/         # Label management
│       ├── notifications/  # Notification preferences
│       ├── integrations/   # Integration settings
│       ├── api/            # API keys and webhooks
│       ├── import-export/  # Data import/export
│       ├── appearance/     # Theme and appearance
│       └── billing/        # Billing (placeholder)
├── onboarding/             # Setup wizard
└── not-found.tsx           # 404 page

Component Hierarchy

Components follow a 3-tier system:

components/
├── ui/                     # Tier 1: shadcn/ui primitives (never modified)
│   ├── button.tsx
│   ├── card.tsx
│   ├── dialog.tsx
│   ├── table.tsx
│   ├── command.tsx         # Command palette primitive
│   ├── sidebar.tsx         # Sidebar primitive
│   └── ...                 # 30+ shadcn/ui components
├── kanban/                 # Tier 2: Kanban board composites
│   ├── kanban-board.tsx    # DragDropContext wrapper
│   ├── kanban-column.tsx   # Droppable status column
│   ├── kanban-card.tsx     # Draggable task card
│   ├── column-header.tsx   # Column title, count, and add button
│   ├── quick-add-card.tsx  # Inline task creation
│   ├── kanban-board-skeleton.tsx
│   └── list-view-skeleton.tsx
├── task/                   # Tier 2: Task composites
│   ├── task-card.tsx       # Task card with status, priority, labels
│   ├── task-row.tsx        # List view task row
│   ├── task-form.tsx       # Create/edit task form
│   ├── task-detail-sidebar.tsx  # Task detail right sidebar
│   ├── task-status.tsx     # Status select dropdown
│   ├── task-priority.tsx   # Priority select dropdown
│   ├── task-labels.tsx     # Label tag display
│   ├── task-id-badge.tsx   # Project prefix + number badge
│   ├── subtask-list.tsx    # Subtask checklist
│   └── comment-thread.tsx  # Comment list with add form
├── pm/                     # Tier 2: PM domain composites
│   ├── stats-card.tsx      # Dashboard KPI card
│   ├── activity-item.tsx   # Activity feed entry
│   ├── cycle-card.tsx      # Sprint cycle card
│   ├── module-card.tsx     # Module card
│   ├── goal-card.tsx       # Goal card with progress ring
│   ├── template-card.tsx   # Project template card
│   ├── automation-rule-card.tsx
│   ├── notification-item.tsx
│   ├── date-badge.tsx      # Due date badge with color coding
│   ├── label-badge.tsx     # Colored label badge
│   ├── member-avatar.tsx   # Team member avatar
│   ├── member-select.tsx   # Member dropdown selector
│   ├── priority-select.tsx # Priority dropdown
│   ├── status-select.tsx   # Status dropdown
│   ├── progress-ring.tsx   # Circular progress indicator
│   ├── empty-state.tsx     # Empty state placeholder
│   ├── confirm-dialog.tsx  # Delete confirmation dialog
│   ├── form-dialog.tsx     # Generic form dialog
│   └── dashboard-skeleton.tsx
├── project/                # Tier 2: Project composites
│   ├── project-card.tsx    # Project card for list view
│   ├── project-header.tsx  # Project page header
│   ├── project-sidebar-nav.tsx  # Project sub-navigation
│   ├── filter-bar.tsx      # Filter and group controls
│   ├── group-header.tsx    # Grouped list section header
│   └── view-switcher.tsx   # Board/list/timeline/calendar toggle
├── charts/                 # Tier 2: Analytics chart composites
│   ├── burndown-chart.tsx  # Sprint burndown chart
│   ├── burnup-chart.tsx    # Sprint burnup chart
│   ├── cumulative-flow.tsx # Cumulative flow diagram
│   ├── cycle-time-chart.tsx # Cycle time distribution
│   ├── velocity-chart.tsx  # Sprint velocity chart
│   ├── distribution-donut.tsx # Status/priority donut chart
│   └── workload-bar.tsx    # Team workload bar chart
├── timeline/               # Tier 2: Timeline / Gantt composites
│   ├── gantt-chart.tsx     # Gantt chart container
│   ├── gantt-bar.tsx       # Individual task bar
│   ├── milestone-marker.tsx # Milestone diamond marker
│   └── today-marker.tsx    # Today line indicator
├── settings/               # Tier 2: Settings composites
│   ├── general-settings-form.tsx
│   ├── members-table.tsx
│   ├── labels-manager.tsx
│   ├── notification-preferences-form.tsx
│   └── settings-nav.tsx
├── layout/                 # Tier 2: Layout components
│   ├── app-sidebar.tsx     # Main navigation sidebar
│   ├── app-header.tsx      # Top header bar
│   ├── command-palette.tsx # Cmd+K command palette
│   ├── workspace-switcher.tsx
│   ├── theme-toggle.tsx    # Light/dark mode toggle
│   ├── skip-link.tsx       # Accessibility skip link
│   └── project-sidebar-nav.tsx
└── a11y/                   # Tier 2: Accessibility utilities
    ├── live-region.tsx     # aria-live announcements
    └── visually-hidden.tsx # Screen reader only text

Backend Infrastructure

lib/
├── supabase/
│   ├── client.ts           # Browser Supabase client
│   ├── server.ts           # Server Supabase client (reads cookies)
│   ├── admin.ts            # Service-role client (bypasses RLS)
│   └── middleware.ts       # Middleware Supabase client
├── actions/                # Next.js Server Actions
│   ├── auth.ts             # Login, register, logout, password reset, OAuth
│   ├── projects.ts         # Project CRUD, member management
│   ├── tasks.ts            # Task CRUD, subtasks, comments, labels, search
│   ├── cycles.ts           # Cycle CRUD, task assignment, completion
│   ├── modules.ts          # Module CRUD, task assignment
│   ├── goals.ts            # Goal CRUD, key results, progress calculation
│   ├── pages.ts            # Wiki page CRUD
│   ├── activities.ts       # Activity log reads and creation
│   ├── analytics.ts        # Dashboard stats, daily metrics, burndown, velocity, cumulative flow, contribution data, status/priority distribution
│   ├── labels.ts           # Label CRUD
│   ├── milestones.ts       # Milestone CRUD
│   ├── automations.ts      # Automation rule CRUD
│   ├── notifications.ts    # Notification reads and mark-as-read
│   ├── team.ts             # Team member management
│   ├── settings.ts         # Workspace settings, API keys, webhooks
│   └── views.ts            # Saved view CRUD
├── queries.ts              # Row-to-TypeScript mappers for all entities
└── utils.ts                # Formatting, date helpers, constants

Database Files

supabase/
├── migrations/
│   ├── 001_schema.sql      # 31 tables with relationships, indexes, enums, and updated_at triggers
│   ├── 002_rls.sql         # Single-workspace RLS policies with is_workspace_member() and is_workspace_admin()
│   └── 003_triggers.sql    # Profile auto-creation, updated_at, task number auto-increment, project count recalculation
├── seed.sql                # 10 team members, 6 projects, 64 tasks, cycles, modules, goals, analytics data, and more
└── drop_all.sql            # Utility to drop all tables for a clean reset

Key Files

File	Purpose
middleware.ts	Protects all dashboard routes, redirects to /login
hooks/use-mobile.ts	Client hook for responsive breakpoint detection
hooks/use-announce.ts	Screen reader announcement hook
hooks/use-focus-trap.ts	Focus trap hook for modals
hooks/use-keyboard-navigation.ts	Keyboard navigation hook
hooks/use-reduced-motion.ts	Respects prefers-reduced-motion
types/index.ts	Application-level TypeScript interfaces
data/seed.ts	Client-side fallback data for demo mode
lib/queries.ts	Maps Supabase rows to typed interfaces