|
1 | | -API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"You have reached your specified API usage limits. You will regain access on 2026-04-01 at 00:00 UTC."},"request_id":"req_011CYrHCd5bajfrRXjhYqSFH"} |
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +Guidance for Claude Code when working in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Sol is the **Rize** monorepo (automatic time tracking). Stack: |
| 8 | +- **api/** - Rails 7.1 GraphQL backend (Ruby 3.3.5) |
| 9 | +- **web/** - Next.js 14 React app (Node 22) |
| 10 | +- **electron/** - Electron desktop app (Node 22) |
| 11 | +- **services/** - Bun TypeScript event consumers/workers |
| 12 | +- **vanity/** - Webflow marketing scripts (deprecated) |
| 13 | +- **voyager/** - Marketing website (Next.js) |
| 14 | +- **puppet/** - Puppeteer server for images/PDFs |
| 15 | +- **chrome/** - Chrome extension |
| 16 | +- **docs/** - Docusaurus site |
| 17 | +- **zapier/** - Zapier integration |
| 18 | + |
| 19 | +## Development Commands |
| 20 | + |
| 21 | +### Start Dev Environment |
| 22 | +```bash |
| 23 | +./scripts/run-dev.sh # All services (requires iTerm2 on macOS) |
| 24 | + |
| 25 | +# Individually: |
| 26 | +cd api && hivemind Procfile.dev # Rails + AnyCable + Sidekiq + Clockwork |
| 27 | +cd web && npm run dev # Next.js (port 3001) |
| 28 | +cd electron && npm run dev # Electron with hot reload |
| 29 | +cd services && hivemind Procfile.dev # Bun services |
| 30 | +``` |
| 31 | + |
| 32 | +### Docker (required before api/services) |
| 33 | +```bash |
| 34 | +cd api && docker-compose up -d |
| 35 | +# TimescaleDB: localhost:15432 | Redis: localhost:16379 |
| 36 | +# Kafka: localhost:9092 | MySQL: localhost:13306 |
| 37 | +``` |
| 38 | + |
| 39 | +### Testing |
| 40 | +```bash |
| 41 | +# API (RSpec) |
| 42 | +cd api && bundle exec rspec |
| 43 | +cd api && bundle exec rspec spec/path/to/file_spec.rb |
| 44 | +cd api && bundle exec rspec spec/path/to/file_spec.rb:42 |
| 45 | + |
| 46 | +# Electron (Jest) |
| 47 | +cd electron && npm test |
| 48 | +cd electron && npm run test:watch |
| 49 | +cd electron && npm run test:coverage |
| 50 | + |
| 51 | +# Web: no active tests (exits 0) |
| 52 | +``` |
| 53 | + |
| 54 | +### Building |
| 55 | +```bash |
| 56 | +cd api && bundle install && rake db:migrate |
| 57 | +cd web && npm run build # gql-gen + tailwind + next build |
| 58 | +cd electron && npm run build # Electron Forge make |
| 59 | +cd services && bun install |
| 60 | +``` |
| 61 | + |
| 62 | +### GraphQL Code Generation |
| 63 | +- `cd web && npm run build` — includes gql codegen |
| 64 | +- `cd electron && npm run dev` — runs gql codegen automatically |
| 65 | + |
| 66 | +## Architecture |
| 67 | + |
| 68 | +### GraphQL API |
| 69 | +Two endpoints: |
| 70 | +- **api/v1** — Public API (OAuth, Zapier) → `api/app/graphql/api/v1/` |
| 71 | +- **private/v1** — Internal API (web, electron) → `api/app/graphql/private/v1/` |
| 72 | + |
| 73 | +### Real-time |
| 74 | +- AnyCable WebSocket subscriptions |
| 75 | +- ActionCable channels: `api/app/channels/` |
| 76 | +- Config: `api/config/cable.yml`, `api/config/anycable.yml` |
| 77 | + |
| 78 | +### Background Jobs |
| 79 | +- Sidekiq (async): `api/config/sidekiq.yml` |
| 80 | +- Clockwork (scheduled): `api/config/clock.rb` |
| 81 | + |
| 82 | +### Event Streaming |
| 83 | +- Kafka publish/consume via `services/consumers/` |
| 84 | +- Config: `api/config/initializers/kafka.rb` |
| 85 | + |
| 86 | +### Databases |
| 87 | +- **PostgreSQL** — primary app data |
| 88 | +- **TimescaleDB** — time-series (separate connection in `database.yml`) |
| 89 | +- **MySQL** — legacy integrations |
| 90 | +- **Redis** — caching, ActionCable, Sidekiq |
| 91 | + |
| 92 | +## Style Guidelines |
| 93 | + |
| 94 | +### JavaScript/TypeScript Tests |
| 95 | +- Use `test()` not `it()` |
| 96 | +- Use `toBeCalled()` not `toHaveBeenCalledWith()` |
| 97 | + |
| 98 | +## Key Config Files |
| 99 | + |
| 100 | +| File | Purpose | |
| 101 | +|------|---------| |
| 102 | +| `api/config/database.yml` | DB connections (primary + timescale) | |
| 103 | +| `api/config/cable.yml` | AnyCable WebSocket config | |
| 104 | +| `api/Procfile.dev` | Dev processes (rails, anycable, sidekiq, clockwork) | |
| 105 | +| `sol.code-workspace` | VS Code multi-folder workspace | |
| 106 | + |
| 107 | +Each subproject needs its own `.env` file (not committed). |
0 commit comments