# CLAUDE.md — AMIR Project Memory ## Behavioral Guidelines **Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment. ### Think Before Coding **Don't assume. Don't hide confusion. Surface tradeoffs.** Before implementing: - State your assumptions explicitly. If uncertain, ask. - If multiple interpretations exist, present them — don't pick silently. - If a simpler approach exists, say so. Push back when warranted. - If something is unclear, stop. Name what's confusing. Ask. ### Simplicity First **Minimum code that solves the problem. Nothing speculative.** - No features beyond what was asked. - No abstractions for single-use code. - No "flexibility" or "configurability" that wasn't requested. - No error handling for impossible scenarios. - If you write 200 lines and it could be 50, rewrite it. Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. ### Surgical Changes **Touch only what you must. Clean up only your own mess.** When editing existing code: - Don't "improve" adjacent code, comments, or formatting. - Don't refactor things that aren't broken. - Match existing style, even if you'd do it differently. - If you notice unrelated dead code, mention it — don't delete it. When your changes create orphans: - Remove imports/variables/functions that YOUR changes made unused. - Don't remove pre-existing dead code unless asked. The test: Every changed line should trace directly to the user's request. ### Goal-Driven Execution **Define success criteria. Loop until verified.** Transform tasks into verifiable goals: - "Add validation" → "Write tests for invalid inputs, then make them pass" - "Fix the bug" → "Write a test that reproduces it, then make it pass" - "Refactor X" → "Ensure tests pass before and after" For multi-step tasks, state a brief plan: 1. [Step] → verify: [check] 2. [Step] → verify: [check] 3. [Step] → verify: [check] Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. --- ## Before Writing Any Code **Read these files first** — they are auto-loaded by Laravel Boost on every session start, and they encode every architectural rule that applies to AMIR: 1. `.ai/guidelines/project-architecture.md` — Action class pattern, controller rules, domain events, model rules, API resources, Spatie policies, queue/Horizon structure for AMIR specifically. 2. `.ai/guidelines/data-conventions.md` — money (cents), IDs (UUID v7), phones (E.164), timestamps (timestampsTz), enums, encrypted fields, migrations. 3. `.ai/guidelines/testing-standards.md` — `AssertsQueryPerformance` trait, Pest patterns, factory conventions, test folder structure, query-count assertions. Then run **Boost's live introspection tools** before planning: - `database_schema` — read the actual current schema; don't assume. - `application_info` — installed packages and versions. - `tinker` — verify model relationships and queries before writing code. Read **`docs/living/`** (all seven files) before planning or troubleshooting. They reflect the actual current state of the codebase, updated every sprint-close. --- ## 1. Project Overview **AMIR** is an AI-native, Malaysia-first SME accounting SaaS — built first for koperasi (cooperative societies) under SKM regulation. The product is multi-tenant, packs-based (Core + Koperasi Pack #1, with Sukmk and Sukkk packs to follow), and delivered as a single Laravel + Inertia + React app with three role contexts (Tenant Admin, Tenant User, Platform Operator). The koperasi pack is the v1 commercial entry point and the SKM tender (S005/2026) deliverable. Solo founder + AI-assisted development. Pre-tender demo deadline: 21 May 2026. Full v1 (production koperasi pilot) target: ~25 August 2026. --- ## 2. Tech Stack (versions are read live by Boost — recorded here for reference) | Layer | Choice | Notes | |---|---|---| | Language | PHP 8.3 | Strict types enabled in every domain file | | Framework | Laravel 12 | Composer `"laravel/framework": "^12.0"` | | Database | PostgreSQL 16 | Malaysia residency (AWS ap-southeast-3) | | Cache + Queue | Redis 7 | Sessions, cache, Horizon queue | | Frontend | Inertia + React 18 + Tailwind 3 | Single-page app, server-rendered routes | | Auth | Sanctum (stateful sessions) + Spatie Permission v6 + Fortify | Cookie-based, CSRF-protected | | Queue | Laravel Horizon | Single Redis-backed queue, multiple supervisors | | Storage | S3-compatible | Malaysia region preferred | | Audit log | spatie/laravel-activitylog v4 | Auto-logging on configured models | | Testing | Pest | Browser tests via Playwright | | Error tracking | Sentry (managed) | PII-scrubbed via beforeSend; replays disabled | --- ## 3. Domain Folder Structure Every business domain owns a folder under `app/Domain/[Name]/`. The 20 modules from ARCHITECTURE.md map to these domains: ``` app/Domain/ Auth/ (Module A — auth, sessions, MFA, login audit) Onboarding/ (Module B — tenant setup wizard) Parties/ (Module C — debtors, creditors, banks, auditors) Accounting/ (Module D — CoA, periods, journal entries, trial balance) Transactions/ (Module E — receipt, payment, journal, contra) Banking/ (Module F — bank reconciliation) FixedAssets/ (Module G — assets + depreciation) Inventory/ (Module H) Members/ (Module I — Koperasi pack: members, shares, subscriptions) ArRahnu/ (Module J — Islamic pawn, gold valuation, auctions) EInvoice/ (Module K — MyInvois, LHDN integration) Reporting/ (Module L — Penyata Kewangan, Trial Balance, P&L, etc.) Surplus/ (Module M — Koperasi pack: surplus distribution, AGM) Signals/ (Module N — anomaly + health-score + LLM explanations) Oversight/ (Module O — PO cross-tenant view, SKM-facing) Operations/ (Module P — PO ops: tenants, packs, billing, alerts) Integrations/ (Module Q — generic integration framework) DataMigration/ (Module R — import/export, opening balances) Pdpa/ (Module S — DSAR, breach, retention, portability) Tax/ (Module T — Cukai Pendapatan + Zakat draft computation) ``` Inside each domain folder: ``` app/Domain/[Name]/ Actions/ — single-purpose action classes (one per business operation) Events/ — domain events emitted by actions Models/ — Eloquent models for this domain only Enums/ — backed enums for status/type values Resources/ — API/Inertia resources Requests/ — FormRequest classes for input validation Policies/ — Spatie-aware authorisation policies Jobs/ — queued jobs (one per async operation) Listeners/ — domain event listeners Services/ — only for genuinely shared logic (avoid; prefer actions) ``` **Cross-domain calls are explicit via Actions, never via direct model coupling.** `Members\Actions\CreateMember` may dispatch a `MemberRegistered` event that `Accounting\Listeners\AllocateMemberAccount` listens to — but `Members\Models\Member` does not import `Accounting\Models\Account`. --- ## 4. Code Pattern Examples ### Controller (thin — delegates to Action) ```php execute( tenantId: $request->user()->currentTenantId(), data: $request->validated(), ); return MemberResource::make($member)->response()->setStatusCode(201); } } ``` ### Action class (single public `execute` method, transactional) ```php $tenantId, 'ic_no_encrypted' => $data['ic_number'], // input field 'ic_number' → storage column 'ic_no_encrypted' (per E3) 'full_name' => $data['full_name'], 'phone_e164' => $data['phone_e164'], 'shares_held' => 0, 'subscription_balance_cents' => 0, 'status' => MemberStatus::Active, ]); event(new MemberRegistered($member->id, $tenantId)); return $member->fresh(); }); } } ``` ### FormRequest (validation only — no business logic) ```php user()->can('create', \App\Domain\Members\Models\Member::class); } public function rules(): array { return [ 'ic_number' => ['required', 'string', 'regex:/^\d{6}-\d{2}-\d{4}$/'], 'full_name' => ['required', 'string', 'max:255'], 'phone_e164' => ['required', 'string', 'regex:/^\+60\d{9,10}$/'], ]; } } ``` --- ## 5. Data Conventions Summary | Convention | Rule | Example | |---|---|---| | Money | Always integer **cents** in `BIGINT` columns named `*_cents`. Never `decimal(N,2)`. | `total_amount_cents BIGINT NOT NULL` | | IDs | **UUID v7** primary keys, generated application-side via `HasUuids` trait override. Never auto-increment. | `id UUID PRIMARY KEY` | | Foreign keys | UUID FKs with explicit `ON DELETE` strategy (RESTRICT default, CASCADE only when child cannot exist independently). | `tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE RESTRICT` | | Status | Backed PHP enum + `string` column; never raw strings in code. | `MemberStatus::Active`, column `status VARCHAR(32)` | | Phones | E.164 format in `phone_e164` columns, `+60123456789` style. | Validated by regex `/^\+60\d{9,10}$/` | | Timestamps | `timestampsTz()` on every table — always timezone-aware. UTC in DB, MYT for display. | `created_at TIMESTAMPTZ NOT NULL` | | Soft deletes | `softDeletes()` on entities with audit-trail lifecycle. | `deleted_at TIMESTAMPTZ NULL` | | Tenant scope | Every tenant-scoped table has `tenant_id UUID NOT NULL`. Use `BelongsToTenant` trait — never manual `where('tenant_id', ...)`. | See `app/Concerns/BelongsToTenant.php` | | Encrypted fields | Sensitive identifiers (NRIC, bank account numbers, TINs) use the **two-column pattern from E3**: `*_encrypted` for ciphertext + `*_hash` for SHA-256 lookup with per-tenant salt. MFA secrets and integration credentials use the single-column `'encrypted'` cast. | `protected $casts = ['ic_no_encrypted' => 'encrypted']` | | Audit | spatie/laravel-activitylog **v5** on every model that needs an audit trail. Import: `Spatie\Activitylog\Models\Concerns\LogsActivity`. Query pattern: `Activity::query()->where('subject_type', Foo::class)->where('subject_id', $id)->count()` — NOT `activity()->forSubject()->count()` (v5 removed that API). | `use LogsActivity;` | Full rules in `.ai/guidelines/data-conventions.md`. --- ## 6. Git Rules ### Branch naming `feature/s{N}-{NN}-{slug}` — example: `feature/s06-01-member-master-crud` `fix/{slug}` for bug-fix branches off `dev` `hotfix/{slug}` for emergency patches off `main` ### Commit message format ``` [type]([scope]): [description] .--. .- .-. ... . -.-. [body — optional, only if context > 1 line] ``` The `.--. .- .-. ... . -.-.` Morse separator is **mandatory** on every commit. The pre-commit guard hook hard-blocks commits without it. `[type]` ∈ `feat`, `fix`, `chore`, `refactor`, `docs`, `test`, `style`, `build`, `ci`. `[scope]` is the domain folder (e.g. `members`, `accounting`) or `core` for cross-cutting. **Forbidden:** - `Co-Authored-By:` lines (hard-blocked by pre-commit guard) - Commits referencing the agent in the message body - Commits with debug artifacts (`dd()`, `dump()`, `console.log`, `var_dump()`) — hard-blocked ### PR rules - Every PR closes one task in `.sprint-backlog.json` - PR description follows the template in `.claude/skills/writing-pr-descriptions.md` - Run `/verify` before opening the PR — 13 steps, mandatory - Every PR must have an associated test (no test = no merge) --- ## 7. DO NOT List (architecture violations specific to AMIR) - ❌ Never query a tenant-scoped model without `BelongsToTenant` trait (silent data leak across tenants) - ❌ Never use `decimal` for money — only integer cents in `BIGINT` - ❌ Never store NRIC in plaintext — use `encrypted` cast - ❌ Never skip `tenant_id` on a new tenant-scoped table (caught by `post-edit-tenant-scope-check.sh` hook) - ❌ Never mutate financial data (transactions, journal entries, posted amounts) directly — always via the appropriate Action class so audit log fires - ❌ Never use raw `where('status', 'XYZ')` — use the backed enum: `where('status', MemberStatus::Active)` - ❌ Never reproduce song lyrics, copyrighted material, real public-figure quotes anywhere in the codebase including comments and seed data - ❌ Never let frontend ALL-CAPS strings drift from PHP enums (caught by `post-edit-enum-sync-check.sh` hook) - ❌ Never write a migration that drops a column without a deprecation sprint first (see `.claude/skills/writing-migrations.md`) - ❌ Never use `console.log` / `dd()` / `dump()` in code that goes to PR — hard-blocked at commit - ❌ Never include PII in analytics events or Sentry breadcrumbs (caught by `PIIGuard` service + `beforeSend` scrubber) - ❌ Never bypass `TenantScope` without the explicit `withoutGlobalScope(TenantScope::class)` call AND a justification comment - ❌ Never call `$request->session()` in middleware without first checking `$request->hasSession()` — API routes (registered via `api:` in `withRouting()`) have no session and will throw `RuntimeException: Session store not set on request` - ❌ Never ship an Action / Listener / Policy class with zero callers — wire it into a Controller, Job, or event listener, or delete it (caught by `dead-code-scanner.sh` hook) - ❌ Never ship a React component in `resources/js/components/` that isn't imported by a page or layout — mount it where it's used or remove it (caught by `orphan-component-scanner.sh` hook) - ❌ Never add a migration column without a corresponding model attribute, Resource field, or Action write — inert columns are debt, not future-proofing (caught by `column-consumer-audit.sh` hook) --- ## 8. Design System Compliance **Before building any page or UI component, read `UI_UX_SPEC.md` Section 7.4 (Component Inventory).** ### Component Usage (mandatory) - Use design system components for ALL UI. Never build raw HTML when a component exists. Use `