# AI Agent Audit Guide — Hospital App

This guide tells an **AI agent** how to audit the hospital/doctor app against the project documentation, find missing topics, and implement or fix them so the app follows the documentation structure.

---

## When to Use This Guide

- User asks to "check if the app matches the documentation"
- User asks to "find what's missing" or "complete missing features"
- User asks to "follow the documentation" or "implement all steps from the doc"
- Before making large changes, run the audit to avoid breaking documented behavior

---

## Step-by-Step Audit Process

### STEP 1: Read the Documentation

1. **Open and read** `docs/PROJECT_DOCUMENTATION.md` in full.
2. **Extract every topic/requirement** from:
   - **Part B:** User Roles & Permissions (each role’s permissions).
   - **Part C:** All functional requirement tables (Lead creation L1.1–L1.4, Lead assignment L2.1–L2.2, Follow-up L3.1–L3.4, Qualification L4.1–L4.3, Conversion CV1–CV6, Patient P1.1–P2.4, Appointment AP1.1–AP3.3, Consultation CO1–CO3, Billing B1.1–B4.3, Follow-up F1–F3, Dashboards D1–D9).
   - **Part D:** All Business Rules **BR-01 through BR-34** (each row is a checklist item).
   - **Part E:** All User Stories **US-01 through US-23** (acceptance criteria).
   - **Part F:** Data Tables/Entities (Lead, Patient, Visit, Appointment, Doctor, Invoice, Billing Item, Payment, Service Master, Lead–Patient Mapping, Hospital).
   - **Part G:** End-to-End Business Flow (sequence of steps).
3. **Build a checklist** of items. Each item should have:
   - **ID** (e.g. BR-05, US-12, L2.1, D4)
   - **Topic name** (e.g. "Lead assignment to agent")
   - **Expected behavior** (from the doc)
   - **Where it should exist** (route name, controller, view path, model, or validation)

**Output:** A list of documentation topics that must exist in the codebase.

---

### STEP 2: Map Documentation to the Codebase

For **each** topic in your checklist:

1. **Routes**
   - Open `routes/web.php` (and `routes/api.php` if used).
   - Find the route(s) that implement this topic (URL, name, method).
   - If no route exists → mark as **MISSING**.

2. **Controller**
   - From the route, get the controller and method (e.g. `LeadController@publicForm`).
   - Open that controller file and confirm the method exists and does what the doc says.
   - If the route points to a missing controller or method → mark as **MISSING** or **BROKEN**.

3. **Views (if applicable)**
   - From the controller, get the view name (e.g. `return view('leads.public-form')`).
   - Check that the Blade file exists under `resources/views/` (e.g. `resources/views/leads/public-form.blade.php`).
   - If the view is missing or empty for a feature that needs UI → mark as **MISSING**.

4. **Models & database**
   - If the topic involves entities (Lead, Patient, Hospital, Invoice, etc.), confirm:
     - Model exists in `app/Models/`.
     - Migrations exist and match (e.g. `hospital_id` on tenant tables).
   - If the topic requires a new table or column that is missing → mark as **MISSING**.

5. **Authorization**
   - Check middleware on the route (`role:Super Admin|Hospital Admin`, etc.).
   - Check that controller logic scopes by `hospital_id` where the doc says "per hospital" or "multi-tenant".
   - If the doc says "only X role" but the route allows others → mark as **INCORRECT**.

**Output:** A **Gap Report**: list of topics that are MISSING, BROKEN, or INCORRECT.

---

### STEP 3: Check Route–Controller Wiring

1. **All `Route::` definitions** in `routes/web.php` must use controllers that are **imported** at the top.
   - Check `use App\Http\Controllers\...` for every controller referenced in routes.
   - **Known issue:** If you see `PaymentController` or `ServiceController` in routes but not in `use` statements, add:
     - `use App\Http\Controllers\PaymentController;`
     - `use App\Http\Controllers\ServiceController;`
2. For each route that uses a controller, verify the controller class and method exist (no typos).

**Output:** List of **broken references** (missing use, missing method, wrong class name).

---

### STEP 4: Check CRM and Optional Modules

1. **CRM routes** (e.g. `/crm/contacts`, `/crm/calls`, `/crm/emails`, `/crm/followups`, `/crm/tasks`, `/crm/analytics`, `/crm/settings`) often point to `DashboardController` methods.
2. For each such route:
   - Confirm the method exists in `DashboardController`.
   - If the method only returns a placeholder view, check if the doc requires a full implementation (list, create, etc.). If yes, mark as **INCOMPLETE**.

**Output:** List of CRM (or other) features that are **stub only** and need real implementation.

---

### STEP 5: Generate the Gap Report

Create a structured report (you can do this in a reply or in a file like `docs/AUDIT_REPORT.md`):

```markdown
# Audit Report — [Date]

## Summary
- Total topics from documentation: X
- Implemented: Y
- Missing: Z
- Broken/Incorrect: W

## Missing Topics
| ID   | Topic            | Expected (route/controller/view)     | Action |
|------|------------------|--------------------------------------|--------|
| L2   | Lead list filter | leads.index, LeadController@index   | Add... |

## Broken / Incorrect
| ID   | Issue | Location | Action |
|------|-------|----------|--------|
| ...  | ...   | ...      | ...    |

## Optional / Incomplete (e.g. CRM stubs)
...
```

---

### STEP 6: Implement Missing or Broken Items

For **each** item in the Gap Report:

1. **Missing route:** Add the route in the correct middleware group in `routes/web.php` (or `api.php`). Add the corresponding `use` for the controller if needed.
2. **Missing controller method:** Add the method to the appropriate controller; return the correct view or redirect.
3. **Missing view:** Create the Blade file under `resources/views/` with the expected name; add minimal content so the page loads (then refine as per doc).
4. **Missing model/migration:** Create migration and model; update controller to use the model and respect `hospital_id` if multi-tenant.
5. **Wrong permissions:** Adjust middleware or controller checks so only the roles stated in the documentation can access the feature; add or fix `hospital_id` scoping where required.

After each change, re-check that:
- The route exists and is reachable.
- The controller method exists and is called.
- The view exists (if applicable).
- Role and tenant rules match the documentation.

---

### STEP 7: Re-run a Quick Verification

1. Walk through your checklist again and confirm every topic is now **Implemented** or **Intentionally deferred**.
2. If the user provided custom documentation in `PROJECT_DOCUMENTATION.md`, ensure every numbered step or requirement there has been considered and either implemented or explicitly listed as out of scope.

---

## Quick Reference: Where Things Live

| What | Where |
|------|--------|
| Documentation (topics to implement) | `docs/PROJECT_DOCUMENTATION.md` |
| Routes | `routes/web.php`, `routes/api.php` |
| Controllers | `app/Http/Controllers/` |
| Views | `resources/views/` |
| Models | `app/Models/` |
| Migrations | `database/migrations/` |
| Role middleware | Check `role:` in routes and controller logic |

---

## Rules for the Agent

1. **Always start by reading** `docs/PROJECT_DOCUMENTATION.md` in full (Parts A through H).
2. **Use Part C (Functional Requirements), Part D (BR-01 to BR-34), Part E (US-01 to US-23), and Part F (Data Tables)** to build the checklist; don’t assume features that aren’t in the doc.
3. **Follow this audit order:** Routes → Controllers → Views → Models/Migrations → Authorization. For each BR, verify the rule is enforced in code (validation, flow, or DB).
4. **Fix broken references first** (e.g. missing `use` for controllers in `routes/web.php`).
5. **Report clearly:** Output a gap report (Missing / Broken / Incomplete) before implementing. You can group by Part (e.g. all missing BRs, all missing US acceptance criteria).
6. **Implement in small steps:** One topic or one fix at a time, then re-verify.
7. **Respect structure:** Same roles (Part B), same flows (Part 8 / Part G), same entities (Part F), and same business rules (Part D) as in the documentation.

---

## Summary

- **Documentation** = `docs/PROJECT_DOCUMENTATION.md` — Hospital Management Solution (Parts A–H: Business context, Roles, Functional requirements, Business Rules BR-01–BR-34, User Stories US-01–US-23, Data tables, Flow, Agent instructions).
- **Audit** = Read doc → Build checklist from Part C, D, E, F → Map each item to routes/controllers/views/models → Find gaps → Report.
- **Fix** = Add or fix routes, controllers, views, models, and permissions so the app matches the documentation.
- **Verification** = Re-check each BR, US acceptance criteria, and the End-to-End Business Flow (Part 8 / Part G).

This way, the AI agent can **identify all missing topics** from the created website and **follow all steps** mentioned in the Hospital Management Solution documentation in a consistent way.
