|
| 1 | +# GitHub Copilot Instructions — ChittyCommand |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +ChittyCommand is a unified life management and action dashboard for the ChittyOS ecosystem. It ingests data from 15+ financial, legal, and administrative sources, scores urgency with AI, recommends actions, and executes them via APIs, email, or browser automation. |
| 6 | + |
| 7 | +- **Repo:** `CHITTYOS/chittycommand` |
| 8 | +- **Deploy:** Cloudflare Workers at `command.chitty.cc` |
| 9 | +- **Stack:** Hono (TypeScript), React + Tailwind (frontend), Neon PostgreSQL via Hyperdrive, Cloudflare R2/KV |
| 10 | +- **Canonical URI:** `chittycanon://core/services/chittycommand` | Tier 5 |
| 11 | + |
| 12 | +## Common Commands |
| 13 | + |
| 14 | +```bash |
| 15 | +npm run dev # Start Hono dev server (wrangler dev) |
| 16 | +npm run build # Typecheck (tsc --noEmit) |
| 17 | +npm run test # Run Vitest tests |
| 18 | +npm run deploy # Deploy to Cloudflare Workers |
| 19 | +npm run ui:dev # Start React frontend (localhost:5173) |
| 20 | +npm run ui:build # Build frontend for Cloudflare Pages |
| 21 | +npm run db:generate # Generate Drizzle migrations |
| 22 | +npm run db:migrate # Run Drizzle migrations |
| 23 | +``` |
| 24 | + |
| 25 | +Secrets are managed via `wrangler secret put` — **never hardcode** them: |
| 26 | + |
| 27 | +```bash |
| 28 | +wrangler secret put PLAID_CLIENT_ID |
| 29 | +wrangler secret put PLAID_SECRET |
| 30 | +wrangler secret put DATABASE_URL |
| 31 | +``` |
| 32 | + |
| 33 | +## Architecture |
| 34 | + |
| 35 | +Single Cloudflare Worker serving API + scheduled cron jobs. Frontend is a separate React SPA (Cloudflare Pages) at `app.command.chitty.cc`. |
| 36 | + |
| 37 | +### Key Files |
| 38 | + |
| 39 | +- `src/index.ts` — Hono app entry point, route mounting, CORS, error handler |
| 40 | +- `src/middleware/auth.ts` — Three auth middlewares: `authMiddleware`, `bridgeAuthMiddleware`, `mcpAuthMiddleware` |
| 41 | +- `src/db/schema.ts` — Drizzle ORM schema (all tables prefixed `cc_`) |
| 42 | +- `src/lib/cron.ts` — Cron sync orchestrator |
| 43 | +- `src/lib/integrations.ts` — Service clients (Mercury, Plaid, ChittyScrape, etc.) |
| 44 | +- `src/lib/urgency.ts` — Deterministic urgency scoring (0–100) |
| 45 | +- `src/lib/validators.ts` — Zod schemas for all request validation |
| 46 | +- `src/routes/` — Route handlers (one file per domain) |
| 47 | +- `src/routes/bridge/` — Inter-service bridge routes |
| 48 | +- `src/routes/mcp.ts` — MCP server (28 tools for Claude integration) |
| 49 | +- `migrations/` — SQL migration files (0001–0007) |
| 50 | +- `ui/` — React frontend (Vite + Tailwind) |
| 51 | + |
| 52 | +## Code Conventions |
| 53 | + |
| 54 | +### TypeScript |
| 55 | + |
| 56 | +- Strict mode is enabled (`"strict": true`). No `any` unless explicitly cast. |
| 57 | +- Target: `ES2022`. Module resolution: `bundler`. |
| 58 | +- All Hono apps/routes are typed: `new Hono<{ Bindings: Env; Variables: AuthVariables }>()`. |
| 59 | +- Import `AuthVariables` from `src/middleware/auth.ts` for route-level context variables. |
| 60 | +- Use `c.set('userId', ...)` and `c.get('userId')` for auth context in middleware and handlers. |
| 61 | + |
| 62 | +### Database (Drizzle ORM) |
| 63 | + |
| 64 | +- All tables are prefixed `cc_` (e.g., `cc_accounts`, `cc_obligations`). |
| 65 | +- Use `uuid` PKs with `.defaultRandom()`. |
| 66 | +- Always include `createdAt` and `updatedAt` timestamps with `{ withTimezone: true }`. |
| 67 | +- Add `index()` on columns used in WHERE/ORDER BY clauses. |
| 68 | +- Monetary values use `numeric` with `{ precision: 12, scale: 2 }`. |
| 69 | +- Use `jsonb` for flexible metadata fields, default to `{}` or `[]`. |
| 70 | +- Import `getDb` from `src/lib/db.ts` to get a database connection. |
| 71 | + |
| 72 | +### Validation (Zod) |
| 73 | + |
| 74 | +- Define all Zod schemas in `src/lib/validators.ts`. |
| 75 | +- Use `@hono/zod-validator` with `zValidator('json', schema)` for request body validation. |
| 76 | +- Validate query params with `zValidator('query', schema)`. |
| 77 | +- Date strings must match `/^\d{4}-\d{2}-\d{2}$/` (YYYY-MM-DD). |
| 78 | +- UUID fields use `z.string().uuid()`. |
| 79 | + |
| 80 | +### Routing (Hono) |
| 81 | + |
| 82 | +- Create one route file per domain in `src/routes/`. |
| 83 | +- Export a named `const xxxRoutes = new Hono()` from each file. |
| 84 | +- Mount routes in `src/index.ts` using `app.route('/api/xxx', xxxRoutes)`. |
| 85 | +- Apply auth middleware at mount time in `src/index.ts`, not inside route files. |
| 86 | +- Always return `c.json(...)` — never return raw strings or untyped responses. |
| 87 | + |
| 88 | +### Error Handling |
| 89 | + |
| 90 | +- Use the global error handler in `src/index.ts` for unhandled errors — it returns `{ error: 'Internal Server Error' }`, never leaking internals. |
| 91 | +- Return `c.json({ error: '...' }, 4xx)` for expected client errors. |
| 92 | +- Catch fetch errors in try/catch; fall through gracefully rather than bubbling errors. |
| 93 | + |
| 94 | +## Auth Patterns |
| 95 | + |
| 96 | +Three auth layers — **do not bypass or modify without security review**: |
| 97 | + |
| 98 | +1. **`authMiddleware`** (`/api/*`) — KV token lookup, then ChittyAuth fallback. Sets `userId` and `scopes`. |
| 99 | +2. **`bridgeAuthMiddleware`** (`/api/bridge/*`) — KV service token (`bridge:service_token`) OR user token. |
| 100 | +3. **`mcpAuthMiddleware`** (`/mcp/*`) — ChittyAuth token first, KV service token fallback (`mcp:service_token`). Bypassed in non-production environments. |
| 101 | + |
| 102 | +Access auth context in handlers via `c.get('userId')` and `c.get('scopes')`. |
| 103 | + |
| 104 | +## Security Requirements |
| 105 | + |
| 106 | +- **Never hardcode** secrets, tokens, API keys, or credentials anywhere in source code. |
| 107 | +- All secrets go through `wrangler secret put` — never in `[vars]` in `wrangler.toml`. |
| 108 | +- KV service tokens: `bridge:service_token`, `mcp:service_token`, `scrape:service_token`. |
| 109 | +- CORS is restricted to approved origins: `app.command.chitty.cc`, `command.mychitty.com`, `chittycommand-ui.pages.dev`, `localhost:5173`. |
| 110 | +- Credentials use 1Password (`op run`) in local development — never expose in terminal output or logs. |
| 111 | +- Error responses must **not** leak internal error messages, stack traces, or sensitive data. |
| 112 | +- All user input must be validated with Zod before use. |
| 113 | +- Use `X-Source-Service: chittycommand` header on all outbound service calls. |
| 114 | + |
| 115 | +## Environment Bindings (Cloudflare Workers) |
| 116 | + |
| 117 | +Available via `c.env` in route handlers and middleware: |
| 118 | + |
| 119 | +| Binding | Type | Purpose | |
| 120 | +|---------|------|---------| |
| 121 | +| `HYPERDRIVE` | Hyperdrive | Neon PostgreSQL connection | |
| 122 | +| `DOCUMENTS` | R2Bucket | Document storage | |
| 123 | +| `COMMAND_KV` | KVNamespace | Auth tokens, sync state, service tokens | |
| 124 | +| `AI` | Ai | Cloudflare AI Gateway | |
| 125 | +| `ENVIRONMENT` | string | `"production"` or `"development"` | |
| 126 | +| `CHITTYAUTH_URL` | string | ChittyAuth service URL | |
| 127 | +| `CHITTYLEDGER_URL` | string | ChittyLedger service URL | |
| 128 | +| `CHITTYFINANCE_URL` | string | ChittyFinance service URL | |
| 129 | +| `CHITTYSCRAPE_URL` | string | ChittyScrape service URL | |
| 130 | +| `CHITTYCONNECT_URL` | string | ChittyConnect service URL | |
| 131 | +| `PLAID_CLIENT_ID` | string (secret) | Plaid API key | |
| 132 | +| `PLAID_SECRET` | string (secret) | Plaid API secret | |
| 133 | + |
| 134 | +Always check if optional URL bindings are present before using them (e.g., `if (c.env.CHITTYAUTH_URL)`). |
| 135 | + |
| 136 | +## Cron Schedule |
| 137 | + |
| 138 | +Defined in `wrangler.toml` and dispatched via `src/lib/cron.ts`: |
| 139 | + |
| 140 | +| Schedule | Purpose | |
| 141 | +|----------|---------| |
| 142 | +| `0 12 * * *` | Daily 6 AM CT: Plaid + ChittyFinance sync | |
| 143 | +| `0 13 * * *` | Daily 7 AM CT: Court docket check | |
| 144 | +| `0 14 * * 1` | Weekly Mon 8 AM CT: Utility scrapers | |
| 145 | +| `0 15 1 * *` | Monthly 1st 9 AM CT: Mortgage, property tax | |
| 146 | + |
| 147 | +## MCP Server |
| 148 | + |
| 149 | +The `/mcp` route exposes 28 tools across 8 domains for Claude integration. Tools return structured JSON: `content: [{ type: "json", json: ... }]`. Auth is handled by `mcpAuthMiddleware`. See `src/routes/mcp.ts` for tool definitions. |
| 150 | + |
| 151 | +## Testing |
| 152 | + |
| 153 | +Tests use Vitest. Run with `npm run test`. Test files live alongside source in `src/` or in a `__tests__` directory. The test configuration is in `vitest.config.ts`. |
| 154 | + |
| 155 | +## PR and Review Policy |
| 156 | + |
| 157 | +- One concern area per PR (security, feature, refactor, schema change, governance). |
| 158 | +- Every PR must include: scope, risk/blast radius, test evidence, rollback plan, and migration impact. |
| 159 | +- Do not bundle governance/ruleset changes with unrelated app logic. |
| 160 | +- Resolve must-fix review comments (security, correctness, compliance, merge blockers) before merge. |
| 161 | +- Do not weaken auth, CORS, or governance controls. |
| 162 | +- Schema changes (`src/db/schema.ts`) require a new SQL migration in `migrations/`. |
| 163 | + |
| 164 | +## ChittyOS Ecosystem Context |
| 165 | + |
| 166 | +ChittyCommand is a **Tier 5 Application** — a consumer of upstream data, not a source of truth. It delegates to: |
| 167 | + |
| 168 | +- **ChittyAuth** — identity and token validation |
| 169 | +- **ChittyFinance** — financial data aggregation |
| 170 | +- **ChittyScrape** — browser automation for portals without APIs |
| 171 | +- **ChittyLedger** — evidence and document ledger |
| 172 | +- **ChittyConnect** — inter-service discovery and connectivity |
| 173 | +- **ChittySchema** — canonical schema validation |
| 174 | +- **ChittyRegister** — service registration and beacon heartbeats |
0 commit comments