# MVC Areas & Separation of Concerns

To enforce high-security module isolation and maintain clear engineering boundaries, the **Asterisk 2** project implements a multi-area ASP.NET Core MVC architecture. This structural separation ensures that unauthenticated public traffic or standard commercial user logic never shares Controller scopes with high-risk system administration routines.

---

## Architectural Area Blueprint

The solution physically categorizes routing engines, views, and controller boundaries into four specialized runtime environments:

```mermaid
graph TB
    %% Core Dispatch Engine
    subgraph RoutingEngine["ASP.NET Core Endpoint Router"]
        Ingress["HTTP Proxy Dispatcher"]
    end

    %% Isolated Application Areas
    subgraph AdminScope["Admin Area (High Privilege)"]
        Ctrl_Admin["AdminController<br/>(AppSettings, Identity CRUD)"]
        Ctrl_DocApi["DocumentationController<br/>(Live Global Document Sync)"]
    end

    subgraph CustomerScope["Customer Area (SaaS Access)"]
        Ctrl_Portal["ProjectController<br/>(Self-Service Provisioning)"]
        Ctrl_RAG["SearchController<br/>(Natural Language Queries)"]
    end

    subgraph AgentScope["Agent Area (Live Telephony)"]
        Ctrl_Console["AgentDashboardController<br/>(Active SIP Sessions)"]
        Ctrl_Flow["VisualAppFlowController<br/>(Stasis Handshakes)"]
    end

    subgraph SupportScope["Support Area (Operations)"]
        Ctrl_Tickets["TicketDispatchController<br/>(System Integration)"]
        Ctrl_Logs["NodeMetricsController<br/>(Cluster Health Polling)"]
    end

    %% Routing Paths
    Ingress -->|"/Admin/*"| AdminScope
    Ingress -->|"/Customer/*"| CustomerScope
    Ingress -->|"/Agent/*"| AgentScope
    Ingress -->|"/Support/*"| SupportScope

    %% Styling Logic
    classDef admin fill:#312e81,stroke:#a855f7,stroke-width:2px,color:#fff,rx:6px,ry:6px;
    classDef cust fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#fff,rx:6px,ry:6px;
    classDef agent fill:#0f172a,stroke:#10b981,stroke-width:2px,color:#fff,rx:6px,ry:6px;
    classDef supp fill:#3b1822,stroke:#f43f5e,stroke-width:2px,color:#fff,rx:6px,ry:6px;

    class AdminScope,Ctrl_Admin,Ctrl_DocApi admin;
    class CustomerScope,Ctrl_Portal,Ctrl_RAG cust;
    class AgentScope,Ctrl_Console,Ctrl_Flow agent;
    class SupportScope,Ctrl_Tickets,Ctrl_Logs supp;
```

---

## Detailed Functional Scope Breakdown

| MVC Area Directory | Target Consumer Group | Core Authentication Requirement | Primary Feature Mapping |
| :--- | :--- | :--- | :--- |
| `/Areas/Admin/` | Seed System Administrators | `Authorize(Roles = "Admin")` | Full application branding layout controls, dynamic share-card graphic overwriting, global tool mappings, user identity provisioning, and project metadata overrides. |
| `/Areas/Customer/` | Active SaaS Licensees | `Authorize(Roles = "Customer")` | Public documentation authoring workspaces, document node structure organization, and read/write scopes limited strictly to their owned project slug spaces. |
| `/Areas/Agent/` | Call Center Operators | `Authorize(Roles = "Agent")` | Low-latency monitoring of assigned PJSIP voice channels, visual call routing flows processing, real-time call transfer state handshakes, and WebRTC streaming handshakes. |
| `/Areas/Support/` | Technical Operational Teams | `Authorize(Roles = "Support")` | Read-only access to operational Asterisk queue logs, channel event loops (`CEL`), call detail archives (`CDR`), and gateway heartbeat metrics mapping. |

---

## Security Scoping & Cross-Area Calling
To prevent horizontal privilege escalation, data repositories utilize scoped services that automatically enforce tenant resolution at the Controller dependency injection layer. System calls traversing areas must authenticate over internal claims loops or validate via explicit API signature keys.