Development Setup

Environment setup and day-to-day development workflows for TimeTiles.

Quick Start


git clone https://github.com/jfilter/timetiles.git
cd timetiles
make init    # installs deps, starts DB, runs migrations, seeds, starts dev server

App: localhost:3000
Dashboard: localhost:3000/dashboard
Docs: localhost:3001 (run pnpm dev in apps/docs)

See Quick Start for prerequisites and database mode options.

Commands

Command	What it does
`make dev`	Start dev server (auto-starts database)
`make check`	Lint + typecheck all packages
`make test`	Run unit + integration tests
`make test-e2e`	Run Playwright E2E tests
`make format`	Format code
`make migrate`	Run database migrations
`make seed`	Seed database with sample data
`make fresh`	Full reset: database + migrate + seed
`make status`	Check environment health

Database Seeding


make seed ARGS="development"            # Rich, realistic data (default)
make seed ARGS="testing --truncate"     # Fast, deterministic data for tests
make seed ARGS="demo"                   # Polished data for demos

Available presets: minimal, testing, e2e, development, demo, benchmark. Add --truncate to clear existing data first.

Workflow

Create a feature branch from main
Make your changes
Run make check — lint and typecheck must pass
Write tests for new functionality
Commit using conventional commits
Open a pull request

Code Standards

TypeScript strict mode — all code must pass strict type checking
Named imports only — import { foo } from 'bar'
No console.log — use logger.info() / logError() from @/lib/logger
React Query for all data fetching — never fetch directly in components
Coordinates in [longitude, latitude] order (GeoJSON standard)
PostGIS for spatial queries — no client-side geo computations

Layered Architecture

The lib/ directory follows a strict import hierarchy:


Layer 0 — Foundation (no lib/ deps)
  utils/, security/, types/, constants/, geospatial/, filters/

Layer 1 — Infrastructure (can import Layer 0)
  services/, database/, middleware/

Layer 2 — Domain (can import Layer 0 + 1)
  import/, ingest/, account/, export/, email/, collections/

Layer 3 — Application (can import anything)
  api/, hooks/, jobs/, blocks/, config/, globals/

Each layer can only import from the same layer or below. Enforced via ESLint.

Migrations


cd apps/web
pnpm payload:migrate:create    # Auto-generate from schema changes
pnpm payload:migrate           # Apply pending migrations

Never create migration files manually — always use Payload’s generator.

Troubleshooting

Problem	Solution
Port 3000 in use	`make kill-dev`
Database connection error	`make down && make up`
Stale state	`make fresh`
TypeScript errors after updates	`pnpm install && make check`