circle

# Circle

> Linear-inspired project management UI template (issues + issue detail pages, projects + project detail pages, a projects table/timeline, teams, cycles, members + member profiles, inbox, documents, and a mock Agent chat) built with Next.js 15 (App Router), React 19, TypeScript, Tailwind CSS v4, shadcn/ui, Zustand and nuqs. Pure front-end: all data is fake and lives in `mock-data/`; mutations are in-memory via Zustand stores; filters/sorting are URL state via nuqs. No backend, no auth.

Key facts for coding agents:

- Page pattern: every route in `app/` wraps a feature component from `components/common/` in `MainLayout` with a header from `components/layout/headers/`.
- Domain types live WITH the fake data in `mock-data/` (Issue, Status + StatusCategory, Cycle, Project, Team, User, LabelInterface, Priority, TeamDocument, InboxItem).
- Issue mutations only go through `store/issues-store.ts`; notifications through `store/notifications-store.ts`; posted project updates through `store/project-updates-store.ts`; agent conversations through `store/agent-chat-store.ts`. Other pages read mock arrays directly.
- Filter "stores" (`filter-store`, `members/projects/team-filter-store`) are nuqs hooks — state lives in the URL. Issue filters use bazza/ui's FiltersState (`?filters=` JSON, with operators) rendered by the vendored `components/data-table-filter` (Linear-style chips). View/display preferences (`view-store`, `display-settings-store`) are persisted Zustand stores.
- Statuses are category-driven (`triage | backlog | unstarted | started | completed | canceled`) — the Active/Backlog/All tabs, cycle progress and insights all derive from `status.category`.
- URLs: `/{orgId}/team/{teamId}/{all|active|backlog|cycles|cycle/active|cycle/upcoming|overview|documents|members|projects|views}`, `/{orgId}/issue/{identifier}`, `/{orgId}/profiles/{userId}`, `/{orgId}/project/{projectId}/{overview|activity|issues}`, `/{orgId}/agent`, `/{orgId}/reviews` (+ `/created`) and `/{orgId}/review/{reviewId}/{,review,changes}` (PR reviews split view: Overview/Guide/Diff; data in `mock-data/reviews.ts`), `/{orgId}/{initiatives|views}` (+ details `/{orgId}/initiative/{initiativeId}` with Overview/Activity/Projects tabs and `/{orgId}/view/{viewId}`; data in `mock-data/initiatives.ts` / `mock-data/views.ts`) plus `/{orgId}/{inbox|my-issues|projects|teams|members|settings}` (`my-issues` = Assigned/Created/Subscribed/Activity tabs, insights + breakdown panels). Settings subpages: `/{orgId}/settings/{preferences|profile|notifications|code-and-reviews|security|connected-accounts|agent-personalization|ai|issue-labels|issue-templates|project-statuses|integrations}`, `/{orgId}/settings/teams/{teamId|new}`, plus placeholder pages `{slas|project-labels|project-templates|project-updates|initiatives|documents|customer-requests|releases|pulse|asks|emojis}` (generic empty state via `components/common/settings/settings-placeholder.tsx`) (components in `components/common/settings/`, nav in `components/layout/sidebar/nav-settings.tsx`). `orgId` is hard-coded to `lndev-ui` in mock data.
- Style: Prettier 3-space indent, Tailwind `cn()` merging, `'use client'` on store-consuming components.

## Docs

- [AI Guide](./AI_GUIDE.md): full architecture map, data model, feature inventory, API-integration seams and conventions
- [README](./README.md): project intro and setup

## Data & state

- [mock-data/status.tsx](./mock-data/status.tsx): 13 workflow statuses, categories, SVG icon builders
- [mock-data/issues.ts](./mock-data/issues.ts): 291 seeded issues, LexoRank ranks, grouping/filter helpers
- [mock-data/cycles.ts](./mock-data/cycles.ts): cycles with capacity/scope/burn-up data + helpers
- [mock-data/issue-details.ts](./mock-data/issue-details.ts): rich issue-page content blocks, activity, relations + deterministic fallback
- [mock-data/project-details.ts](./mock-data/project-details.ts): rich project-page content (description blocks, milestones, updates, activity) + deterministic fallback
- [mock-data/agent.ts](./mock-data/agent.ts): agent examples + deterministic canned replies
- [store/issues-store.ts](./store/issues-store.ts): the only mutable issue state (CRUD + filters)
- [store/agent-chat-store.ts](./store/agent-chat-store.ts): agent conversations (multi-chat, streamed replies)

## Key UI

- [components/layout/main-layout.tsx](./components/layout/main-layout.tsx): app shell used by every page
- [components/common/issues/all-issues.tsx](./components/common/issues/all-issues.tsx): grouped issue views (list/board, category tabs, insights panel)
- [components/common/issues/cycle-issues.tsx](./components/common/issues/cycle-issues.tsx): cycle-scoped issue view with side panels
- [components/common/issues/details/issue-details.tsx](./components/common/issues/details/issue-details.tsx): issue detail page (blocks renderer, activity, properties panel)
- [components/layout/headers/display-options.tsx](./components/layout/headers/display-options.tsx): Linear-style Display popover (grouping, ordering, display properties)
- [components/common/issues/issue-filter-columns.tsx](./components/common/issues/issue-filter-columns.tsx): filterable columns config + applyIssueFilters (operators)
- [components/data-table-filter](./components/data-table-filter): vendored bazza/ui filter component (chips UI, filter fns)
- [components/common/cycles/cycles.tsx](./components/common/cycles/cycles.tsx): cycles timeline with burn-up chart
- [components/common/members/member-profile.tsx](./components/common/members/member-profile.tsx): member profile (Assigned/Created tabs, identity panel, breakdowns)
- [components/common/projects/details/project-overview.tsx](./components/common/projects/details/project-overview.tsx): project detail tabs (overview/activity/issues) + properties panel
- [components/common/projects/projects.tsx](./components/common/projects/projects.tsx): projects page — All table + Active timeline (gantt) + Health/Teams/Leads insights panel
- [components/common/agent/agent-chat.tsx](./components/common/agent/agent-chat.tsx): functional mock Agent chat (canned replies, word-by-word streaming)

## Optional

- [components/ui](./components/ui): vendored shadcn/ui primitives — do not hand-edit unless customizing the design system