iamdoubz
0cdac0bcdc
MB1 (spec 13). Decision 0005: our own Android/iPhone app, Expo in the mobile repo, user portal only, no push in v1. - mobile_devices (migration 0013): one-time pairing codes from My settings (QR or server + code, 10 minutes), traded by the app for an spm_ device token that acts as its user and never as an admin - POST /api/me/mobile-devices/pair (web session only), POST /api/mobile/pair, GET/DELETE /api/me/mobile-devices - signing out everywhere (password change or reset, disabling) removes paired phones too - My settings: Mobile app section with the QR code and paired phones - mobile/ (its own repo) ignored here
75 lines
4.7 KiB
Markdown
75 lines
4.7 KiB
Markdown
# AGENTS.md — Rules for AI coding agents working on SelfPhoneNG
|
|
|
|
Read this file first, every time. Then read `docs/spec/00-overview.md`.
|
|
Then read ONLY the spec files your task points to.
|
|
|
|
## What this project is
|
|
|
|
A fully open source, self-hosted business phone system (PBX) with a web admin
|
|
panel, a browser softphone, voicemail, IVRs, ring groups, queues and desk-phone
|
|
provisioning: the same kind of product as 3CX. The user brings their own SIP
|
|
trunk / phone number (the reference provider is **voip.ms**).
|
|
|
|
We do **not** write a SIP stack. **Asterisk** does all SIP and audio work. We
|
|
write the software around it: database, config generator, API, web UI.
|
|
|
|
## How the spec is organized
|
|
|
|
| File | What it covers | Read it when |
|
|
|---|---|---|
|
|
| `docs/spec/00-overview.md` | Goals, architecture, tech stack, repo layout, glossary, numbering plan | Always |
|
|
| `docs/spec/01-infrastructure.md` | Docker, Asterisk image, static Asterisk config, networking, NAT, reverse proxy, env vars | Working on Docker or Asterisk base config |
|
|
| `docs/spec/02-data-model.md` | Every database table and column | Touching the DB or any feature that stores data |
|
|
| `docs/spec/03-config-generator.md` | How DB rows become Asterisk config and dialplan (the most important file) | Working on call routing or any telephony feature |
|
|
| `docs/spec/04-backend-api.md` | API server, auth, AMI client, live state, background jobs, REST endpoints, WebSocket events | Working on the backend |
|
|
| `docs/spec/05-web-ui.md` | Admin panel, user portal, browser softphone | Working on the frontend |
|
|
| `docs/spec/06-voipms.md` | voip.ms trunk setup, inbound DID handling, SMS, E911 | Working on trunks, SMS, or emergency calling |
|
|
| `docs/spec/07-provisioning.md` | Desk phone auto-provisioning (Yealink, Grandstream, Polycom) and mobile apps | Working on provisioning |
|
|
| `docs/spec/08-security-ops.md` | Security, backups, monitoring, legal requirements | Before any release, and when touching auth or networking |
|
|
| `docs/spec/09-roadmap.md` | Milestones, ordered tasks, acceptance criteria | Picking your next task |
|
|
| `docs/spec/11-contacts.md` | Contacts: the builtin phonebook or Contrack, lookup, the Contrack timeline | Working on contacts or caller names |
|
|
| `docs/spec/12-sso.md` | Single sign-on: OpenID Connect (Keycloak and others) and LDAP/LDAPS | Working on sign-in, users or roles |
|
|
| `docs/spec/13-mobile.md` | The Android/iPhone app (`mobile` repo): pairing, device tokens, its tasks | Working on the mobile app or its API |
|
|
|
|
## Hard rules
|
|
|
|
1. **Do one task at a time.** Tasks have IDs like `M3-T2` in `09-roadmap.md`.
|
|
Do not start the next task until the current one meets every acceptance criterion.
|
|
2. **Follow the file paths in the spec exactly.** Do not invent new top-level folders.
|
|
3. **Do not add dependencies** that are not listed in `00-overview.md` §4 without
|
|
writing the reason in `docs/decisions/NNNN-title.md` (one short paragraph).
|
|
4. **Everything must be open source.** Never add a closed-source or binary-only
|
|
component. In particular: do NOT install Asterisk's binary `codec_opus` or `codec_g729` modules.
|
|
5. **Never hand-edit generated Asterisk files** (`/etc/asterisk/selfphoneng/*.conf`).
|
|
Change the generator in `apps/api/src/generator/` instead.
|
|
6. **Every generator change needs a golden-file test** (see `03-config-generator.md` §12).
|
|
7. **Never log secrets** (SIP passwords, API keys, session tokens, voicemail PINs).
|
|
8. **Validate all API input with zod.** Never build SQL by string concatenation.
|
|
Never put raw user input into dialplan text without running it through the
|
|
sanitizers in `03-config-generator.md` §2.
|
|
9. **If the spec is unclear**, choose the simplest option that fits the spec,
|
|
leave a comment `// TODO(spec): <question>` at that spot, and list the question
|
|
in your final summary. Do not stop working to wait for an answer.
|
|
10. **Asterisk dialplan snippets in this spec are reference code.** They are
|
|
believed correct for Asterisk 24 but must be proven by the tests named in
|
|
each task. If a snippet is wrong, fix it, and update the spec file in the same commit.
|
|
|
|
## Commands (once M0 is done)
|
|
|
|
```bash
|
|
pnpm install # install everything
|
|
pnpm dev # api + web in watch mode (needs docker compose up -d postgres asterisk)
|
|
pnpm test # all unit tests (vitest)
|
|
pnpm lint # eslint + prettier check
|
|
pnpm typecheck # tsc --noEmit in every package
|
|
pnpm db:migrate # run drizzle migrations
|
|
docker compose up -d # full stack
|
|
```
|
|
|
|
Before you say a task is done, `pnpm lint && pnpm typecheck && pnpm test` must all pass.
|
|
|
|
## Commit style
|
|
|
|
`<area>: <what changed>`, e.g. `generator: add ring group hunt strategy`.
|
|
One task per commit (or a short series), with the task ID in the body.
|