# Quick Reference Card

> Essential commands and info for daily development

## 🚀 Daily Commands

### Start Everything

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

### Individual Services

```bash
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](../deploy/README.md#staging-runner-runs-on-the-laptop-not-railway)
> for why and how to point `pnpm dev:runner` at staging's Redis + API.

### Database

```bash
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

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

### Build

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

### Docker

```bash
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

```typescript
// 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

```bash
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

```bash
GITHUB_CLIENT_ID="..."
GITHUB_CLIENT_SECRET="..."
OPENAI_API_KEY="..."
ANTHROPIC_API_KEY="..."
```

## 🎯 Common Tasks

### Add Dependency

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

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

### Create Migration

```bash
# 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

```bash
psql "$DATABASE_URL" -c "SELECT 1"
```

### Clear Everything

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

## 🐛 Troubleshooting

### Ports in Use

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

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

### Database Won't Connect

```bash
# Check if running
docker ps | grep postgres

# Restart
pnpm docker:down
pnpm dev:docker

# Check logs
pnpm docker:logs postgres
```

### Build Errors

```bash
# Clean and rebuild
pnpm clean
pnpm install
pnpm build

# Clear Turbo cache
rm -rf .turbo
```

## 📚 Documentation

| Topic | Link |
|-------|------|
| **Getting Started** | [docs/getting-started/](./getting-started/README.md) |
| **Architecture** | [docs/architecture/](./architecture/README.md) |
| **Development** | [docs/development/](./development/README.md) |
| **Frontend** | [docs/frontend/](./frontend/README.md) |
| **Backend** | [docs/backend/](./backend/README.md) |
| **Full Index** | [docs/README.md](./README.md) |

## 🎓 Learning Path

**New to Project?**

1. [Quick Start](./getting-started/quick-start.md)
2. [System Overview](./architecture/overview.md)
3. [Local Setup](./development/local-setup.md)

**Starting Development?**

1. [Local Setup](./development/local-setup.md)
2. [Architecture Overview](./architecture/README.md)
3. [Database Setup](./packages/database-package.md)

**Understanding Architecture?**

1. [System Overview](./architecture/overview.md)
2. [Technology Stack](./architecture/technology-stack.md)
3. [Monorepo Structure](./architecture/monorepo-structure.md)

## 🔗 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?

1. Check troubleshooting sections in docs
2. Review error logs carefully
3. Ask in team chat
4. Create issue with details

---

**Print this page and keep it handy!** 📄

*Last updated: 2025-01-10*