Quick Reference Card

Essential commands and info for daily development

🚀 Daily Commands

Start Everything

pnpm dev            # All services
pnpm dev:docker     # Just infrastructure (DB + Redis)

Individual Services

pnpm dev:web        # Frontend (http://localhost:5173)
pnpm dev:api        # Backend (http://localhost:4000)
pnpm dev:runner     # Test-execution worker (drains the Redis queue)

Skip pnpm dev:runner and run_suite calls will queue runs that stay PENDING forever — there is no consumer. pnpm dev starts everything, including the runner, in one go.

Staging note: the staging runner also runs on the laptop, not on Railway — see deploy/README.md for why and how to point pnpm dev:runner at staging's Redis + API.

Database

pnpm db:studio      # Visual DB browser
pnpm db:migrate     # Apply migrations
pnpm db:generate    # Generate migration from schema
pnpm db:seed        # Seed test data

Code Quality

pnpm lint           # Run linter
pnpm format:all     # Format code
pnpm type:check     # TypeScript check
pnpm test           # Run tests

Build

pnpm build          # Build all packages
pnpm clean          # Clean build artifacts

Docker

pnpm docker:up      # Start PostgreSQL + Redis
pnpm docker:down    # Stop all containers
pnpm docker:logs    # View logs

🌐 Service URLs

Service	URL	Port
Web App	http://localhost:5173	5173
API	http://localhost:4000	4000
AI Service	http://localhost:8000	8000
PostgreSQL	localhost:5433	5433
Redis	localhost:6379	6379
Drizzle Studio	http://localhost:4983	4983

📁 Project Structure

izri/
├── apps/
│   ├── web/          # React Router frontend
│   └── api/          # Hono + tRPC backend
├── packages/
│   ├── database/     # Drizzle ORM
│   ├── trpc/         # tRPC routers
│   ├── auth/         # Authentication
│   ├── shared/       # Common utilities
│   └── ai-service/   # Python AI
├── docs/             # Documentation
└── docker/           # Dockerfiles

🔑 Key Files

File	Purpose
`.env`	Local environment config
`package.json`	Root scripts
`turbo.json`	Build pipeline
`pnpm-workspace.yaml`	Workspace config
`docker-compose.yml`	Local infrastructure

💾 Database Quick Reference

Schema Location

packages/database/src/schema.ts

Common Queries

// Select
const projects = await db.select().from(projects)

// Where
const project = await db
  .select()
  .from(projects)
  .where(eq(projects.id, id))

// Insert
await db.insert(projects).values({ ... })

// Update
await db
  .update(projects)
  .set({ name: 'New Name' })
  .where(eq(projects.id, id))

// Delete
await db.delete(projects).where(eq(projects.id, id))

🔧 Environment Variables

Required

DATABASE_URL="postgresql://postgres:postgres@localhost:5433/izri"
API_URL="http://localhost:4000"
VITE_API_URL="http://localhost:4000"
APP_URL="http://localhost:5173"
BETTER_AUTH_SECRET="your-secret-here"
JWT_SECRET="your-jwt-secret"
REDIS_URL="redis://localhost:6379"

Optional

GITHUB_CLIENT_ID="..."
GITHUB_CLIENT_SECRET="..."
OPENAI_API_KEY="..."
ANTHROPIC_API_KEY="..."

🎯 Common Tasks

Add Dependency

# To specific package
pnpm --filter @izri/web add react-query

# To root (dev dependency)
pnpm add -w -D vitest

Create Migration

# 1. Edit packages/database/src/schema.ts
# 2. Generate migration
pnpm db:generate
# 3. Review SQL in packages/database/migrations/
# 4. Apply migration
pnpm db:migrate

Test Database Connection

psql "$DATABASE_URL" -c "SELECT 1"

Clear Everything

pnpm clean
rm -rf node_modules apps/*/node_modules packages/*/node_modules
pnpm install
pnpm build

🐛 Troubleshooting

Ports in Use

# Check what's using a port
lsof -ti:5173
lsof -ti:4000

# Kill process
kill $(lsof -ti:5173)

Database Won't Connect

# Check if running
docker ps | grep postgres

# Restart
pnpm docker:down
pnpm dev:docker

# Check logs
pnpm docker:logs postgres

Build Errors

# Clean and rebuild
pnpm clean
pnpm install
pnpm build

# Clear Turbo cache
rm -rf .turbo

📚 Documentation

Topic	Link
Getting Started	docs/getting-started/
Architecture	docs/architecture/
Development	docs/development/
Frontend	docs/frontend/
Backend	docs/backend/
Full Index	docs/README.md

🎓 Learning Path

New to Project?

Starting Development?

Understanding Architecture?

🔗 External Resources

React Router: https://reactrouter.com
tRPC: https://trpc.io
Drizzle ORM: https://orm.drizzle.team
Hono: https://hono.dev
Tailwind CSS: https://tailwindcss.com

💡 Tips

✅ Use pnpm dev to start everything at once
✅ Keep Drizzle Studio open for DB inspection
✅ Check .env.shared.example for all available variables
✅ Run pnpm env:generate after editing .env.shared
✅ Use Turbo's caching (rebuilds are fast!)
✅ Restart API server after schema changes

🆘 Need Help?

Check troubleshooting sections in docs
Review error logs carefully
Ask in team chat
Create issue with details

Print this page and keep it handy! 📄

Last updated: 2025-01-10