# AGENTS.md — Asterisk Voicemail Portal

Project: mail.txt3.net Asterisk PBX + MySQL voicemail store + React portal (vm.txt3.net)
Backend repo: `/home/jp/Work/asterisk-voicemail` (this repo)
Frontend repo: `/home/jp/Work/voicemail-ui`
Deployed frontend: `/home/txt3/domains/vm.txt3.net/public_html/`
Deployed backend: `/opt/vm-transcribe/`

---

## Directory layout

- `src/vm_api.py` — FastAPI JSON API (:8098). Apache proxies `/api/` → :8098.
- `src/vm_web.py` — Original FastAPI HTML portal (:8099).
- `src/vm_store.py` — MySQL-backed voicemail store.
- `src/vm_contacts.py` — MySQL-only contact backend (no CardDAV/Google).
- `frontend/` — React frontend synced from `/home/jp/Work/voicemail-ui`.
- `apache/vm.txt3.net.conf` — Apache vhost (CSP relaxed, Let's Encrypt cert).

---

## Services

- `vm-api.service` → :8098 (JSON API). Active unit.
- `vm-portal.service` → :8099 (HTML portal).
- `apache2` → :443 with per-subdomain cert for vm.txt3.net.

Auth: voicemail `pin` from `voicemail.conf`. No separate portal passwords.

---

## Frontend stack

- React + react-router-dom (createBrowserRouter + RouterProvider).
- TanStack Query for data fetching/mutations.
- Vite build → `dist/` → rsync to `/home/txt3/domains/vm.txt3.net/public_html/`.
- Dark cyber theme in `src/index.css` with neon accents.

---

## Backend conventions

- Use `_fmt_time()` for timestamps; it must handle both `datetime.datetime` and unix timestamps.
- SQL queries via PyMySQL `%s` placeholders; always use `con.execute()` and `con.commit()`.
- Callerid matching: strip spaces/quotes with `REPLACE(REPLACE(callerid, ' ', ''), '"', '')` before LIKE comparison.
- Normalize UK numbers to E.164 in backend; 0-prefix fallback in queries.

---

## Sudo / deployment

- Sudo requires password. Use `SUDO_ASKPASS=/home/jp/.hermes/askpass.sh` with `sudo -A <cmd>`.
- `sudo bash <script>` is blocked (nested root shell). Run privileged steps as individual `sudo -A <cmd>` calls.
- Deploy backend: `sudo -A cp /home/jp/asterisk-vm/vm_api.py /opt/vm-transcribe/vm_api.py && sudo -A systemctl restart vm-api`.
- Deploy frontend: `sudo -A rsync -a --exclude 'node_modules' --exclude 'dist' /home/jp/Work/voicemail-ui/ /home/txt3/domains/vm.txt3.net/public_html/`.

---

## Git

- Remote: Gitea self-hosted. Push needs `jp-account` Gitea PAT with `repo` scope.
- Frontend sync: `rsync -a /home/jp/Work/voicemail-ui/ frontend/` then commit under `frontend/`.

---

## Contacts & matching

- Contacts live in MySQL `contacts` table.
- E.164 is canonical; UK storage often 0-prefixed.
- Creating/updating a contact backfills `messages.contact_name`/`contact_email` for matching callerids.

---

## Known gotchas

- Chrome overrides dark inputs: use bare `input` selector, hardcode `background: #0a0e17`, reset `appearance`, set `-webkit-text-fill-color`.
- React hook rules: no `useMemo`/`useState` inside `.map()`. Hooks must be at component top level.
- Do NOT push to origin from this session unless explicitly asked; push is currently blocked by Gitea 401 (uid 0).