# AGENTS.md

## Project Structure

```
workspace/
├── apps/
│   ├── go-crm/            # Go server (Chi), HTML templates, hot-reload via air
│   ├── whatsapp-crm/      # Next.js 14 App Router, sql.js (browser SQLite), Kanban
│   ├── whatsapp-sync/     # Node.js WhatsApp sync service
│   ├── whatsapp-reader/   # Standalone message reader
│   └── timesfm-forecast/  # Streamlit + TimesFM (Python/uv)
├── data/                  # SQLite DBs: go-crm.db, whatsapp.db
├── data-engineering/      # Udacity DE portfolio (standalone, no unified build)
└── skills/                # dbt reference templates
```

---

## Developer Commands

### go-crm (primary)
```bash
cd apps/go-crm
go run main.go              # plain dev (no hot-reload)
air                         # hot-reload dev (uses .air.toml)
go build -o go-crm main.go  # binary
./go-crm                    # run binary

go mod tidy                 # clean go.mod/go.sum

# DB: /workspace/data/go-crm.db  (hardcoded path — do not change)
# WhatsApp session: /workspace/data/whatsapp.db  (hardcoded path)
```

### whatsapp-crm
```bash
cd apps/whatsapp-crm
npm run dev     # Next.js dev server 0.0.0.0:3000
npm run build   # production build
npm run lint    # ESLint
npm run test    # Jest (uses tests/setup.ts)
```

### whatsapp-sync
```bash
cd apps/whatsapp-sync
npm run start   # node src/index.js
npm run dev     # node --watch src/index.js
npm run sync    # node src/sync.js
npm run test    # Jest (mocks qrcode-terminal + whatsapp-web.js)
```

### whatsapp-reader
```bash
cd apps/whatsapp-reader
node index.js   # main script
node sync.js    # sync script
# no test script
```

### timesfm-forecast
```bash
cd apps/timesfm-forecast
uv venv && source .venv/bin/activate
uv pip install -e .
ruff check .           # lint (dev dep)
timesfm-app            # run Streamlit app

# See apps/timesfm-forecast/README.md for CUDA/CPU wheel guidance
```

---

## Important Quirks

### WhatsApp auth sessions
- `.wwebjs_auth/` directories store session state — do not commit these
- `whatsapp-sync` uses `better-sqlite3` for persistence
- `whatsapp-crm` browser-side uses `sql.js` (WebAssembly, no native deps)

### go-crm auth
- `X-Internal-Secret` header required on requests (value: `internal-secret`)
- WhatsApp connector init URL: `http://localhost:8080`

### Docker
```bash
docker compose up whatsapp-crm          # CRM only
docker compose --profile sync up        # CRM + sync
docker compose --profile test up       # test runner
```

### go-crm hot-reload
- Uses `air` (not `go run`) — configured in `.air.toml`
- Build excludes `_test.go` and `vendor/`, `tmp/`, `assets/`

### TypeScript config (whatsapp-crm, whatsapp-sync)
- `strict: true` in tsconfig.json
- Path alias `@/*` maps to `src/*`

### Testing mocks
- `whatsapp-sync` has manual mocks for `qrcode-terminal` and `whatsapp-web.js` in `tests/__mocks__/`

---

## What to Avoid

- Do not use `go run main.go` for development — use `air`
- Do not commit `.wwebjs_auth/` or `.wwebjs_cache/` directories
- Do not change hardcoded DB paths in `main.go`
- The `data-engineering/` projects are standalone — no shared build or test commands