Chronos Calendar Development
This skill provides comprehensive guidance for working with the Chronos calendar application codebase - a modern calendar app with both web and desktop versions.
Project Overview
Chronos is a monorepo-based calendar application featuring:
Web app built with React Router, Supabase, Tailwind CSS, and shadcn/uiDesktop app using Electron wrapperGoogle Calendar integrationAI scheduling capabilitiesMinimalist UI design**Tech Stack:**
**Web**: React Router, Supabase, Tailwind CSS, shadcn/ui**Desktop**: Electron**Build Tool**: Turbo (monorepo management)**Package Manager**: pnpm**Language**: TypeScriptDevelopment Commands
Monorepo Root Commands
```bash
Run both web and desktop in development
pnpm dev:desktop
Run web app only
pnpm dev:web
Run desktop app only
pnpm dev:electron
Build all apps
pnpm build
Build desktop specifically
pnpm build:desktop
```
Web App Commands (apps/web)
```bash
Development server (port 5174)
pnpm dev
Testing
pnpm test # Run once
pnpm test:watch # Watch mode
Code quality
pnpm lint # ESLint
pnpm typecheck # TypeScript checking
pnpm format # Prettier
Production
pnpm build
pnpm start # Production server
```
Desktop App Commands (apps/desktop)
```bash
Development (requires web app on port 5174)
pnpm electron:dev
Build
pnpm electron:build
Package for distribution
pnpm dist
```
Architecture Guidelines
Monorepo Structure
`/apps/web/` - React Router web application`/apps/desktop/` - Electron desktop wrapper`/packages/` - Shared packages`turbo.json` - Build pipeline configuration`pnpm-workspace.yaml` - Workspace configurationWeb App Architecture
**Routing** (React Router file-based):
Routes: `/apps/web/app/routes/`API routes: `api.*.ts` filesPages: `*.tsx` filesLayouts: `_calendar.tsx` pattern**State Management**:
Server-side loading via React Router loaders/actionsClient-side with React hooksSupabase for auth and real-time data**Styling**:
Tailwind CSS utilitiesshadcn/ui components: `pnpm dlx shadcn@latest add [component]`Dark/light theme support**Key Dependencies**:
`@supabase/supabase-js` - Auth and database`@googleapis/calendar` - Google Calendar API`openai` - AI scheduling`date-fns` - Date utilities`lucide-react` - IconsDesktop Architecture
Electron wrapper loading web appMain process: `apps/desktop/src/main.ts`Protocol handling: `chronos://`Multi-platform builds (Mac/Windows/Linux)Critical Implementation Patterns
API Route Pattern
All API endpoints follow: `api.{resource}.{action}.ts`
Examples:
`api.calendar.events.ts` - Fetch events`api.calendar.update-event.ts` - Update events`api.calendar.schedule-with-ai.ts` - AI schedulingReact Router v7 Response Utilities
**CRITICAL**: React Router v7 uses `data()` not `json()`:
```typescript
// ❌ WRONG - Causes import errors
import { json } from "react-router";
return json({ message: "Hello" }, { status: 200 });
// ✅ CORRECT - Use data()
import { data } from "react-router";
return data({ message: "Hello" }, { status: 200 });
```
Both `data()` and `redirect()` are imported from `"react-router"` (not `"@react-router/node"`).
Authentication Flow
1. Supabase Google OAuth authentication
2. Session managed by Supabase SSR
3. Protected routes check auth in loaders
4. Callback: `/auth/callback`
Protected paths requiring authentication:
`/auth/callback` - OAuth callback handlerDashboard/calendar routesComponent Organization
UI components: `/app/components/ui/` (shadcn/ui)Feature components: `/app/components/` (business logic)Utilities: `/app/lib/` (helpers, API clients)Environment Variables
Required in `.env` for web app:
`VITE_SUPABASE_URL` - Supabase project URL`VITE_SUPABASE_ANON_KEY` - Supabase anonymous keyGoogle OAuth credentials (as needed)OpenAI API key (for AI features)Testing Guidelines
Framework: VitestTest files: `*.test.ts` or `*.test.tsx`Setup: `vitest.setup.ts`Always run tests before committingCode Style Principles
1. **TypeScript** - Full type safety
2. **Functional components** - Use React hooks
3. **Server-side first** - Prefer server data loading
4. **Simplicity** - Readable code over clever solutions
5. **Consistency** - Follow existing codebase patterns
Migration Notes
The project migrated from Remix to React Router v7:
Use `react-router` commands (not `remix`)Routes config: `app/routes.ts`Entry points: `entry.client.tsx`, `entry.server.tsx`Response helper: `data()` replaces Remix's `json()`Common Tasks
Adding UI Components
```bash
Install shadcn/ui component
pnpm dlx shadcn@latest add [component-name]
```
Running Full Development Environment
```bash
Terminal 1: Web app
cd apps/web
pnpm dev
Terminal 2: Desktop app
cd apps/desktop
pnpm electron:dev
```
Type Checking Across Workspace
```bash
From root
pnpm typecheck
```
Troubleshooting
**Desktop app blank screen**: Ensure web app is running on port 5174**Import errors with `json()`**: Switch to `data()` from React Router v7**Environment variables not loading**: Check `.env` file in `apps/web/`**Build failures**: Run `pnpm install` at root to sync workspace dependencies