ADR-002: Frontend Framework

Status

Accepted

Context

Cornerstone requires a frontend framework to build a responsive SPA with these key UI requirements:

• Interactive Gantt chart with drag-and-drop task rescheduling
• Dependency arrows and critical path highlighting
• Responsive layout (desktop, tablet, mobile-friendly)
• Forms for CRUD operations on work items, budget entries, household items
• Document preview integration (Paperless-ngx thumbnails and metadata)
• Calendar and list views alongside the Gantt chart

The Gantt chart is the most complex UI component and a core differentiator of the application. The chosen framework must have strong ecosystem support for data visualization and drag-and-drop interactions.

Alternatives Considered

Vue 3

• Excellent developer experience with Composition API
• Good TypeScript support (improved significantly in Vue 3)
• Smaller ecosystem for Gantt chart libraries compared to React
• Available Gantt libraries (e.g., DHTMLX Gantt for Vue) are mostly commercial or less maintained
• Strong community, but fewer open-source interactive charting components

Svelte / SvelteKit

• Excellent performance with compile-time reactivity
• Smaller bundle sizes by default
• Very limited ecosystem for Gantt chart components
• Fewer drag-and-drop libraries available
• Smaller community makes it harder to find solutions for complex UI requirements
• Would require building the Gantt chart largely from scratch using D3 or Canvas

React 19

• Largest ecosystem of any frontend framework
• Multiple Gantt chart options: gantt-task-react, frappe-gantt-react, or custom D3/SVG-based solutions
• Mature drag-and-drop libraries: dnd-kit (modern, accessible), react-beautiful-dnd
• Extensive table/grid components for list views (TanStack Table)
• Strong TypeScript support with well-maintained type definitions
• Large pool of documentation, examples, and community solutions
• React 19 brings performance improvements with the new compiler

Decision

Use React 19 as the frontend framework, with React Router v7 for client-side routing.

Consequences

Positive

• Rich ecosystem for all UI requirements (Gantt, drag-and-drop, tables, forms)
• Multiple Gantt chart implementation paths available (library-based or custom SVG/D3)
• Strong TypeScript integration with generic component patterns
• Easier to hire/onboard contributors due to React's popularity
• TanStack ecosystem (Query, Table, Form) provides excellent data management patterns

Negative

• Larger bundle size compared to Svelte (mitigated by code splitting and tree shaking)
• JSX syntax is polarizing (some developers prefer template-based approaches)
• React's rendering model requires care with memoization for complex visualizations
• More boilerplate than Svelte for simple components