Cronny Development Guide

Guide for working with the Cronny codebase - a web scraping and job scheduling platform for Austrian real estate websites.

Project Overview

Cronny is a TypeScript monorepo consisting of:

When to Use This Skill

Use this skill when:

1. Working with the Cronny codebase

2. Adding new web scraping strategies

3. Debugging job execution or scheduling

4. Making database schema changes

5. Developing frontend features with the Mantine UI

6. Setting up the development environment

Development Workflow

Initial Setup

1. **Verify Node.js version**

- Project uses Node.js 22.14.0 (managed via Volta)

- Check current version: `node --version`

2. **Install dependencies**

- CRITICAL: Use `yarn`, never `npm`

- Run: `yarn install`

3. **Set up environment variables**

- Copy `packages/client/.env.example` to `packages/client/.env.development`

- Default: `VITE_API_URL=http://localhost:3000`

4. **Initialize database**

- Run migrations: `yarn migrate` (from `packages/server/`)

- Verify with Drizzle Studio: `yarn studio`

Daily Development

1. **Start development servers**

- Run `yarn dev` from project root (starts both client:5173 and server:3000)

- OR run separately:

- Client: `cd packages/client && yarn dev`

- Server: `cd packages/server && yarn dev`

2. **Debugging**

- Use `yarn debug` to attach Node.js debugger to server

3. **Code quality**

- Run ESLint: `cd packages/client && yarn lint`

- Run tests: `cd packages/server && yarn test`

Production Build & Deployment

1. **Build for production**

- Run: `yarn build` from root

- Builds both client and server packages

2. **Run production**

- Run: `yarn start:prod` (runs migrations + starts server)

Architecture Understanding

Monorepo Structure

```

packages/

├── client/ # React frontend with Mantine UI

├── server/ # Hono backend with SQLite

└── types/ # Shared TypeScript interfaces

```

Key Patterns

1. **Strategy Pattern (Web Scraping)**

- Location: `packages/server/src/strategies/`

- Each website has its own strategy class

- All implement standardized `Runner` interface

- Tests in `tests/strategies/` with HTML/JS fixtures in `tests/fixtures/`

2. **Job Scheduling System**

- Jobs stored in SQLite with cron expressions

- Executed via node-cron with dynamic strategy loading

- Core files:

- `packages/server/src/schedule.ts` - Scheduling logic

- `packages/server/src/cron.ts` - Cron execution

- `packages/server/src/run.ts` - Job coordination

3. **Database Schema**

- Entities: Jobs, Runs, Results, Clients, ClientJobs

- Uses Drizzle ORM with SQLite

- Schema: `packages/server/src/db/schema.ts`

- Database file: `packages/server/.data/db.sqlite`

4. **API Communication**

- Client: `packages/client/src/api/client.ts`

- Development: Direct requests to `http://localhost:3000`

- Production: Relative URLs (same origin)

- Auto-handles auth tokens

Common Tasks

Adding a New Web Scraping Strategy

1. **Create strategy file**

- Path: `packages/server/src/strategies/[site-name].ts`

- Implement `Runner` interface

- Use Playwright for browser automation

2. **Add test file**

- Path: `tests/strategies/[site-name].test.ts`

- Use Vitest framework

3. **Create test fixtures**

- Path: `tests/fixtures/[site-name]/`

- Include sample HTML/JS files for testing

4. **Register strategy**

- Update strategy registry/loader in server code

5. **Test thoroughly**

- Run: `cd packages/server && yarn test`

Making Database Changes

1. **Modify schema**

- Edit: `packages/server/src/db/schema.ts`

- Use Drizzle ORM table definitions

2. **Run migrations**

- Execute: `cd packages/server && yarn migrate`

- Verify changes in Drizzle Studio: `yarn studio`

3. **Test migrations**

- Tests use separate `.data` directory

- Run: `yarn test` to verify

Developing Frontend Features

1. **Key directories**

- Routes: `packages/client/src/routes/` (file-based routing)

- API hooks: `packages/client/src/api/` (React Query)

- Components: Use Mantine UI library

2. **Main entry points**

- Root: `packages/client/src/main.tsx`

- App: `packages/client/src/App.tsx` (auth, routing, theme)

3. **API integration**

- Use React Query hooks from `src/api/`

- Client configured in `src/api/client.ts`

Debugging & Testing

1. **Server debugging**

- Run: `yarn debug`

- Attach debugger to Node.js process

2. **Run tests**

- From server: `yarn test`

- Uses Vitest with HTML/JS fixtures

3. **Database inspection**

- Launch: `yarn studio` (Drizzle Studio GUI)

- Located at: `packages/server/.data/db.sqlite`

Key File Reference

Server Core

Client Core

Strategy Development

Additional Features

Authentication

Notifications

Important Constraints

1. **Package Manager**: ALWAYS use `yarn`, never `npm`

2. **Node Version**: Must use Node.js 22.14.0

3. **ES Modules**: Codebase uses ES modules throughout

4. **Database**: SQLite file at `packages/server/.data/db.sqlite`

5. **Ports**: Client (5173), Server (3000)

Common Issues & Solutions

1. **Port already in use**

- Kill processes on ports 3000 or 5173

- OR change port in env configuration

2. **Database locked**

- Close Drizzle Studio if open

- Check for hanging test processes

3. **Module not found errors**

- Re-run: `yarn install`

- Check Node.js version matches 22.14.0

4. **API connection issues (dev)**

- Verify `VITE_API_URL=http://localhost:3000` in `.env.development`

- Ensure server is running on port 3000

Getting Started Checklist