# Alma — Project Instructions

Multi-tenant tertiary-institution SaaS. Laravel 13 + Vue 3 + Inertia 2
+ PostgreSQL. Tenancy via stancl/tenancy (single-DB, `tenant_id` as
`string`). Spatie Permission in teams mode.

- **Repo root:** `/Users/reji/dev/almasos.com` (the directory was once
  `almasms.com`; the GitHub remote is still `rnayettey/almasms`). Always
  root git + artisan commands here — the shell's default cwd may be a
  different project.
- **Branch flow:** develop → staging → main. Work on `develop`. Never
  auto-promote staging → main (explicit release decision only).
- **Commit trailer:** end commit messages with
  `Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>`.

## Source of truth — the system map

`docs/alma-system-map.html` is the **canonical source of truth** for
build status, deferred work, and proposed upgrades. It is
version-controlled with the code.

**After EVERY build task, before considering it done, update the map:**

1. **Module status** — flip a module / sub-feature to shipped (`s:'ship'`,
   sub `'y'`) when it lands. Remove its `remaining:` tooltip once fully
   shipped. The summary counts recompute automatically.
2. **Deferred builds** (`DEFERRED` array) — add anything consciously
   parked, with a one-line "why deferred".
3. **Proposed upgrades** (`PROPOSALS` array) — capture any new idea that
   surfaces during or after the build (module, idea, short note).
4. Keep `docs/PRODUCT_SCOPE.md` and `docs/USER_JOURNEYS.md` reconciled
   too, and bump the map's header `stamp`.
5. A standalone mirror lives at
   `/Users/reji/dev/assets/almasos/alma-system-map.html` — keep it in
   sync (`cp` the repo copy over it) so the external artefact never
   drifts.

The map's data lives in plain JS arrays near the bottom of the file
(`MODULES`, `DEFERRED`, `PROPOSALS`) — edit those, no build step needed.

## Build conventions (observed pattern — keep consistent)

Per feature: migration → models → permissions (+ `PermissionSeeder`) →
controller → routes (admissions sub-routes go **before** the catch-all
`admin/admissions/{application}`) → adminNav → Vue pages → **smoke test**
→ CHANGELOG entry → commit. Run `npm run build` to catch TS/Vue errors.
Every mutation goes through `ActivityLogger`. Leave smoke-test records in
place (the user reuses them).