# Architecture Flow Diagram
## 🔄 Complete Request Flow
```
┌─────────────────────────────────────────────────────────────────────────┐
│ CLIENT (Laravel Frontend) │
│ │
│ User clicks "Ask AI" → Sends message + Bearer Token │
└────────────────────────────────────┬────────────────────────────────────┘
│
│ POST /chat
│ Authorization: Bearer <token>
│ {"message": "Show my contracts"}
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ WEB CHAT API (FastAPI) │
│ src/web_chat/main.py │
│ │
│ 1. Extract Bearer token from header │
│ 2. Call get_user_from_token(token) │
│ ├─ Check cache (15 min TTL) │
│ ├─ If cached: return user data (10ms) │
│ └─ If not: call Laravel API (150ms) │
│ │
│ 3. Laravel API: GET /api/get-login-user-data │
│ Returns: │
│ { │
│ "user_id": 123, │
│ "role_id": 10, // Dealership Admin │
│ "organization_id": 1, │
│ "dealership_id": 5, │
│ "email": "user@example.com", │
│ "permissions": ["contract.index", "contract.create", ...] │
│ } │
│ │
│ 4. Create UserContext object │
│ UserContext( │
│ user_id=123, │
│ role=Role.DEALERSHIP_ADMIN, │
│ bearer_token=token, │
│ organization_id=1, │
│ dealership_id=5, │
│ permissions=[...] │
│ ) │
└────────────────────────────────────┬────────────────────────────────────┘
│
│ process_query(message, user_context)
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ ORCHESTRATOR (Query Processor) │
│ src/orchestrator/processor.py │
│ │
│ 1. Connect to MCP Server │
│ 2. Get available tools from MCP │
│ 3. Filter tools by RBAC │
│ ├─ User role: DEALERSHIP_ADMIN │
│ ├─ Available: DEALERSHIP_TOOLS + AUTHENTICATED_TOOLS │
│ └─ Filtered: ["get_dealership_contracts", "get_user_profile", ...] │
│ │
│ 4. Call LLM with filtered tools │
│ ├─ Provider: OpenAI/Claude/Gemini │
│ ├─ Message: "Show my contracts" │
│ └─ Tools: [filtered tool list] │
│ │
│ 5. LLM decides to call: get_dealership_contracts() │
│ │
│ 6. Execute tool via MCP │
│ ├─ Inject user context into tool arguments │
│ ├─ args["user_id"] = 123 │
│ ├─ args["organization_id"] = 1 │
│ ├─ args["dealership_id"] = 5 │
│ ├─ args["bearer_token"] = token │
│ └─ args["permissions"] = [...] │
└────────────────────────────────────┬────────────────────────────────────┘
│
│ call_tool("get_dealership_contracts", args)
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ MCP SERVER (FastMCP) │
│ src/mcp_server/server.py │
│ │
│ 1. Receive tool call with injected context │
│ 2. Route to registered tool │
│ 3. Call tool function with arguments │
└────────────────────────────────────┬────────────────────────────────────┘
│
│ get_dealership_contracts(user_context, ...)
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ TOOL (Your Implementation) │
│ src/mcp_server/tools/contracts/get_contracts.py │
│ │
│ 1. Receive UserContext │
│ user_context = UserContext( │
│ user_id=123, │
│ role=DEALERSHIP_ADMIN, │
│ bearer_token=token, │
│ dealership_id=5, │
│ permissions=["contract.index", ...] │
│ ) │
│ │
│ 2. Check permissions │
│ if "contract.index" not in user_context.permissions: │
│ return error("Missing permission") │
│ │
│ 3. Call Laravel API │
│ GET /api/contracts │
│ Headers: {"Authorization": f"Bearer {user_context.bearer_token}"} │
│ │
│ 4. Laravel returns contracts │
│ { │
│ "data": [ │
│ {"id": 1, "vendor": "ABC", "dealership_id": 5, ...}, │
│ {"id": 2, "vendor": "XYZ", "dealership_id": 5, ...}, │
│ {"id": 3, "vendor": "DEF", "dealership_id": 8, ...} ← Other │
│ ] │
│ } │
│ │
│ 5. Filter by hierarchy │
│ filtered = RBAC.filter_data_by_hierarchy( │
│ data=contracts, │
│ user_context=user_context │
│ ) │
│ Result: Only contracts where dealership_id=5 │
│ │
│ 6. Return envelope response │
│ wrap_response( │
│ tool_name="get_dealership_contracts", │
│ data={"contracts": filtered, "count": 2} │
│ ) │
└────────────────────────────────────┬────────────────────────────────────┘
│
│ Return tool result
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ ORCHESTRATOR (Continued) │
│ │
│ 7. Receive tool result │
│ 8. Send result back to LLM │
│ 9. LLM generates natural language response │
│ "You have 2 contracts: │
│ 1. ABC Corp - expires 2024-12-31 │
│ 2. XYZ Inc - expires 2025-06-30" │
└────────────────────────────────────┬────────────────────────────────────┘
│
│ Return final answer
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ WEB CHAT API (Response) │
│ │
│ 10. Save conversation history │
│ 11. Return response to client │
│ { │
│ "success": true, │
│ "response": "You have 2 contracts: ...", │
│ "history": [...] │
│ } │
└────────────────────────────────────┬────────────────────────────────────┘
│
│ HTTP Response
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ CLIENT (Display Response) │
│ │
│ User sees: "You have 2 contracts: ..." │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## 🔐 RBAC Filtering at Different Stages
```
┌─────────────────────────────────────────────────────────────────────────┐
│ RBAC FILTERING STAGES │
└─────────────────────────────────────────────────────────────────────────┘
Stage 1: TOOL VISIBILITY (Orchestrator)
├─ Input: All MCP tools
├─ Filter: RBAC.is_tool_allowed(user_role, tool_name)
├─ Output: Only tools user's role can access
└─ Effect: LLM only sees allowed tools
Example:
Dealership Admin sees:
✅ get_dealership_contracts
✅ get_user_profile
✅ upload_contract
❌ get_organization_contracts (org-level only)
❌ manage_organizations (admin only)
───────────────────────────────────────────────────────────────────────────
Stage 2: PERMISSION CHECK (Tool Level)
├─ Input: Tool called by LLM
├─ Filter: Check user_context.permissions
├─ Output: Allow/deny tool execution
└─ Effect: Fine-grained permission control
Example:
Tool: upload_contract
Check: "contract.create" in user_context.permissions
Dealership Admin: ✅ Has permission → Proceed
Dealership Viewer: ❌ No permission → Return error
───────────────────────────────────────────────────────────────────────────
Stage 3: DATA FILTERING (Tool Level)
├─ Input: Data from Laravel API
├─ Filter: RBAC.filter_data_by_hierarchy(data, user_context)
├─ Output: Only data user can see
└─ Effect: Hierarchy-aware data access
Example:
Laravel returns 100 contracts:
- 30 from Organization A, Dealership 1
- 40 from Organization A, Dealership 2
- 30 from Organization B, Dealership 3
Org Admin (Org A): Sees 70 contracts (Dealership 1 + 2)
Platform Admin (Platform with Dealership 1): Sees 30 contracts
Dealership Admin (Dealership 1): Sees 30 contracts
Dealership Admin (Dealership 2): Sees 40 contracts
───────────────────────────────────────────────────────────────────────────
Stage 4: ACTION FILTERING (Tool Level)
├─ Input: User action (create/update/delete)
├─ Filter: user_context.can_write / can_manage
├─ Output: Allow/deny action
└─ Effect: Prevent viewers from modifying data
Example:
Action: Delete contract
Dealership Admin: ✅ can_manage=True → Proceed
Dealership User: ✅ can_write=True → Check permission
Dealership Viewer: ❌ can_write=False → Return error
```
---
## 🎯 Permission Check Decision Tree
```
┌─────────────────────────────────────────────────────────────────────────┐
│ SHOULD I CHECK PERMISSIONS? │
└─────────────────────────────────────────────────────────────────────────┘
Tool Type: READ-ONLY (list, get, view)
├─ RBAC already filtered tool visibility ✅
├─ No write/delete actions
└─ Decision: NO permission check needed
└─ Just filter data by hierarchy
Example: get_dealership_contracts, get_user_profile
───────────────────────────────────────────────────────────────────────────
Tool Type: CREATE/UPDATE
├─ User might be a viewer (read-only)
├─ Need to prevent modifications
└─ Decision: YES, check can_write
└─ if not user_context.can_write: return error
Example: create_contract, update_contract
───────────────────────────────────────────────────────────────────────────
Tool Type: DELETE
├─ Sensitive action
├─ Only managers/admins should delete
└─ Decision: YES, check can_manage + specific permission
└─ if not user_context.can_manage: return error
└─ if "resource.delete" not in permissions: return error
Example: delete_contract, delete_vendor
───────────────────────────────────────────────────────────────────────────
Tool Type: ADMIN ACTION
├─ System-wide changes
├─ Only admins should access
└─ Decision: YES, check is_global_admin or is_organization_level
└─ if not user_context.is_global_admin: return error
Example: manage_organizations, system_configuration
───────────────────────────────────────────────────────────────────────────
Tool Type: SPECIFIC FEATURE
├─ Laravel has specific permission for this
├─ Need to check exact permission
└─ Decision: YES, check specific Laravel permission
└─ if "specific.permission" not in permissions: return error
Example: contracts.renewal, invoice.paid, users.global_filters
```
---
## 📊 Data Flow Example: "Show my contracts"
```
User Message: "Show my contracts"
User Role: Dealership Admin (role_id=10)
Dealership: ID 5
Organization: ID 1
───────────────────────────────────────────────────────────────────────────
Step 1: Authentication
├─ Bearer token validated
├─ User data cached
└─ UserContext created
├─ user_id: 123
├─ role: DEALERSHIP_ADMIN (10)
├─ organization_id: 1
├─ dealership_id: 5
└─ permissions: ["contract.index", "contract.show", ...]
───────────────────────────────────────────────────────────────────────────
Step 2: Tool Filtering (RBAC)
├─ All MCP tools: 20 tools
├─ Filter by role: DEALERSHIP_ADMIN
└─ Allowed tools: 8 tools
├─ ✅ get_dealership_contracts
├─ ✅ get_dealership_vendors
├─ ✅ upload_contract
├─ ✅ get_user_profile
├─ ❌ get_platform_contracts (platform-level)
├─ ❌ get_organization_contracts (org-level)
└─ ❌ manage_organizations (admin-only)
───────────────────────────────────────────────────────────────────────────
Step 3: LLM Decision
├─ Query: "Show my contracts"
├─ Available tools: [8 filtered tools]
└─ LLM chooses: get_dealership_contracts()
───────────────────────────────────────────────────────────────────────────
Step 4: Tool Execution
├─ Tool: get_dealership_contracts
├─ Injected context:
│ ├─ user_id: 123
│ ├─ organization_id: 1
│ ├─ dealership_id: 5
│ ├─ bearer_token: <token>
│ └─ permissions: [...]
└─ Tool logic:
├─ Check permission: "contract.index" ✅
├─ Call Laravel: GET /api/contracts
├─ Laravel returns: 100 contracts (all orgs/dealerships)
└─ Filter by hierarchy:
├─ Keep: organization_id=1 AND dealership_id=5
└─ Result: 12 contracts
───────────────────────────────────────────────────────────────────────────
Step 5: LLM Response
├─ Tool result: {"contracts": [12 items], "count": 12}
├─ LLM generates: "You have 12 contracts for your dealership..."
└─ Return to user
───────────────────────────────────────────────────────────────────────────
Total Time: ~200ms
├─ Auth (cached): 10ms
├─ LLM call: 100ms
├─ Tool execution: 50ms
└─ Response: 40ms
```
---
## 🔄 Comparison: Laravel vs MCP RBAC
```
┌─────────────────────────────────────────────────────────────────────────┐
│ LARAVEL APPROACH │
└─────────────────────────────────────────────────────────────────────────┘
Route::group(['middleware' => ['auth:sanctum', 'permission']], function () {
Route::get('/api/contracts', [ContractController::class, 'index'])
->middleware('permission:contract.index');
Route::post('/api/contracts', [ContractController::class, 'store'])
->middleware('permission:contract.create');
Route::delete('/api/contracts/{id}', [ContractController::class, 'destroy'])
->middleware('permission:contract.delete');
});
Flow:
1. Request hits route
2. auth:sanctum validates token
3. permission middleware checks Laravel permission
4. If allowed → Controller executes
5. If denied → 403 Forbidden
Pros:
✅ Simple and explicit
✅ Enforced at route level
✅ Standard Laravel pattern
Cons:
❌ Fixed per endpoint
❌ No dynamic tool filtering
❌ LLM sees all endpoints (can't filter)
───────────────────────────────────────────────────────────────────────────
┌─────────────────────────────────────────────────────────────────────────┐
│ MCP APPROACH │
└─────────────────────────────────────────────────────────────────────────┘
# RBAC at orchestrator level
allowed_tools = RBAC.get_allowed_tools(user_context.role)
# Tool receives full context
@mcp.tool()
async def get_contracts(user_context: UserContext):
# Check permissions
if "contract.index" not in user_context.permissions:
return error("Missing permission")
# Call Laravel API
response = await call_laravel_api(user_context.bearer_token)
# Filter by hierarchy
filtered = RBAC.filter_data_by_hierarchy(data, user_context)
return filtered
Flow:
1. Bearer token validated at API entry
2. RBAC filters tools by role
3. LLM only sees allowed tools
4. Tool checks permissions + filters data
5. Return filtered result
Pros:
✅ Dynamic tool filtering (LLM-friendly)
✅ Hierarchy-aware data filtering
✅ Flexible permission checks
✅ Single auth check (cached)
✅ Context-aware tools
Cons:
❌ More complex than middleware
❌ Permission checks in tool code
───────────────────────────────────────────────────────────────────────────
VERDICT: MCP approach is BETTER for AI agents because:
1. LLM only sees tools user can actually use
2. Tools can make intelligent decisions based on context
3. Hierarchy filtering is automatic
4. More flexible than fixed routes
5. Better user experience (no "permission denied" errors)
```
---
## 🎓 Key Takeaways
1. **Authentication happens once** at API entry (Bearer token)
2. **RBAC filters tools** before LLM sees them
3. **Tools receive full user context** automatically
4. **Permission checks** happen at tool level (flexible)
5. **Data filtering** happens at tool level (hierarchy-aware)
6. **No middleware needed** - MCP architecture is better for AI
**Your current implementation is excellent!** 🎉
