# LegalAssistance — Architecture (developer reference)

> Internal developer doc. Not shipped to clients. Customer overview: `README.md`. Security/dead-code: `_AUDIT/LegalAssistance/findings.md`.

**Module:** `LegalAssistance` · **Load order:** 25 · **Version:** 2.0.10 · **Author:** Marcus-Law · **Requires:** EspoCRM ≥ 8.0.0

## What it is
Generates the Israeli legal-aid "**דוח גישה ישירה**" (direct-access report) as a DOCX, straight from JSON params (no intermediate entity), and uploads it to the case folder. It is reached as a **SmartAssistant agent tool** — Shira runs an 8-step Hebrew interview to collect the data, then calls the tool. Since Phase 3, the legal tools live in **shira-hermes**, not ai-gateway; this extension is now minimal.

## File-by-file
| File | Purpose |
|---|---|
| `files/.../SmartAssistant/Tools/DirectAccessReportGenerator.php` | **Core:** JSON params → DOCX via PHPWord `TemplateProcessor` (checkbox mapping) → upload to case folder via NetworkStorageIntegration (local fallback). **IDOR via caseId — S1; param→DOCX injection — S3; temp file — S4.** |
| `files/.../Resources/module.json` | Module order 25. |
| `files/.../Resources/metadata/app/smartAssistant.json` | Registers the `generate_direct_access_report` tool handler. |
| `files/.../Resources/metadata/entityDefs/Case.json` | **Empty `{}`** (no Case extension in v2.0.10) — D5. |
| `files/.../Resources/i18n/{en_US,he_IL,fa_IR}/Case.json` | Light "LegalAssistance" tab labels. (`Global.json` empty — D3.) |
| `plugins/legal-assistance/tools.json` | Shira tool schema for `generate_direct_access_report` (50+ params). |
| `plugins/legal-assistance/prompts.json` | Hebrew `casePromptAppend` — the 8-step interview flow. |
| `templates/direct-access-report.docx` | The DOCX template (39 KB binary). |
| `scripts/AfterInstall.php` | Creates the DocumentTemplate, clears cache, ensures i18n dirs. **ai-gateway deploy removed (Phase 3) — only a doc-comment remains.** |
| `scripts/AfterUninstall.php` | ⚠️ **Drops phantom v1.x tables + Case columns + i18n — destructive + dead (S2/D1).** |

### Dead/reference clutter (not packaged, but in the repo — D2/D4)
`docs/examples/entity-reference-legalaid.md` (59 KB, removed architecture), `field_mapping.md`, `legal-docx-v3-fixed/` (Node.js reference), `.env.example`, `טופס`, old zips v1.0.0–1.3.2.

## Dependencies
- **NetworkStorageIntegration (strong, graceful):** report upload to the case folder; falls back to local attachment storage if disabled.
- **SmartAssistant (hard, runtime):** the tool is only reachable via SmartAssistant's `executeTool` — it inherits SmartAssistant's IDOR (S1).
- **shira-hermes (soft):** Shira loads the `plugins/` tool + prompt to drive the interview.

## Post-install gotchas
- Requires SmartAssistant + Shira configured; NetworkStorageIntegration recommended for case-folder filing.
- Fix the destructive `AfterUninstall` (S2) before any external release — it can wipe legal-aid data.