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).

3.0 KiB Raw Blame History