# emran025/super_admin_agent_app architecture

> Architecture diagram of the GitHub repository emran025/super_admin_agent_app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/emran025/super_admin_agent_app
- Repository: https://github.com/emran025/super_admin_agent_app

## Overview

1. **Repository shape**
   This is a three-part monorepo:
   - `agent/` contains the architecture constitution, security rules, and domain contracts.
   - `super_admin_agent_app/` is the Flutter mobile agent implementation.
   - `otp_server/` is the Laravel backend that the agent pairs with and calls into.

2. **Architectural governance layer**
   The `agent/` directory is not runtime code; it is the system’s control plane for design constraints. It defines:
   - clean architecture and dependency direction,
   - zero-trust and signing rules,
   - domain boundaries for `auth_2fa`, `otp_gateway`, and `payment_observation`,
   - server obligations and allowed outputs.
   These documents act as the repo’s canonical architectural policy.

3. **Mobile application is the main runtime client**
   `super_admin_agent_app/` is a Flutter app built with a strict Clean Architecture split:
   - `presentation/` for UI, pages, widgets, and Cubit state management,
   - `domain/` for entities, repositories, use cases, and value objects,
   - `data/` for remote data sources, DTOs, and repository implementations,
   - `shared/` for cross-cutting services and infrastructure.
   The app is organized by feature, not by transport layer.

4. **Three primary business domains in the app**
   The app’s runtime logic is centered on three workflows:
   - **Push 2FA**: receive a challenge, show it to the user, record approval/denial, sign and submit the response.
   - **SMS OTP gateway**: receive OTP dispatch commands and execute local SMS sending.
   - **Payment observation**: register observation sessions, parse inbound SMS payment notifications, match them to payment intent, and report observations.
   Each domain has its own entities, repositories, use cases, and transport adapters.

5. **Trust, identity, and cryptography are shared services**
   The mobile app’s `shared/` layer provides the security substrate:
   - Android Keystore-backed signing,
   - secure storage for secrets and pairing data,
   - canonical JSON generation,
   - nonce generation,
   - append-only SQLite audit logging.
   These services are used to produce verifiable, replay-resistant messages across all domains.

6. **Device-side messaging and event handling**
   The app includes infrastructure for:
   - WebSocket message routing,
   - separate WebSocket handlers for auth, OTP, and payment observation,
   - SMS receiving and SMS sending,
   - permission handling for Android device capabilities.
   This suggests the mobile agent is event-driven: it listens for server or external-system messages, then dispatches them to the relevant domain use case.

7. **Pairing and linked-system management**
   Pairing is a first-class domain in the mobile app:
   - pairing tokens can be scanned,
   - systems can be linked, unlinked, paired, or unpaired,
   - capability grants appear to scope what a linked system is allowed to do.
   The dashboard and pairing pages show that trust establishment is a user-visible workflow, not just a backend concern.

8. **Backend runtime: Laravel OTP server**
   `otp_server/` is a Laravel application that exposes the server side of the architecture. Its key parts are:
   - API controllers for agent heartbeat, reports, pairing, OTP commands, push challenges, and external-system login approval,
   - web controllers for manual testbed flows,
   - middleware for capability checks and external-system verification,
   - services for canonical JSON, payload encryption, signature verification, and 2FA challenge orchestration.
   This server is the authority for issuing challenges, accepting agent reports, and coordinating trusted relationships.

9. **Server persistence and security model**
   The server stores the state needed for replay protection and trust tracking:
   - `agents`
   - `external_systems`
   - `otp_dispatches`
   - `two_factor_challenges`
   - `used_nonces`
   - `users`
   The presence of nonce tracking, challenge tables, and agent/external-system linkage indicates strong emphasis on authentication, anti-replay, and auditability.

10. **Real-time and asynchronous coordination**
    The backend includes broadcasting and event classes such as:
    - `AgentCommandDispatched`
    - `TwoFactorChallengeIssued`
    - `TwoFactorDecisionMade`
    The config also includes queue, cache, and Reverb broadcasting support. This implies some flows are asynchronous or event-driven, especially around push 2FA and live state updates.

11. **External-system integration boundary**
    The server has explicit “external” API controllers and verification middleware, which means not every client is the mobile agent. There is a separate boundary for third-party or upstream systems that:
    - request login approval,
    - send OTP dispatch commands,
    - link to the agent through pairing.
    This is a separate trust zone from the mobile agent itself.

12. **Testbed and operator-facing flows**
    The Laravel app contains dedicated web views for:
    - system pairing,
    - push 2FA test flows,
    - SMS gateway test flows,
    - a general hub/welcome experience.
    These are likely not core runtime dependencies, but they are important for manual validation and demoing the end-to-end architecture.

13. **API/data-flow summary for an architecture diagram**
    The main flows to diagram are:
    - **Pairing**: external system or operator → Laravel pairing API/web flow → mobile agent stores paired system and capability grant.
    - **Push 2FA**: backend issues challenge → agent receives challenge → user approves/denies → agent signs response → backend verifies and emits decision.
    - **OTP dispatch**: external system → backend command API → agent sends local SMS → agent reports delivery status back.
    - **Payment observation**: agent receives SMS locally → parses/matches → sends observation report to backend.
    These flows all cross a cryptographic trust boundary and are mediated by signed, canonicalized messages.

14. **Tooling and delivery**
    The repo includes GitHub Actions workflows for CI and server deployment, plus standard Flutter/Laravel build files and test suites. The implementation is therefore split between mobile client delivery and backend deployment, with tests present at unit and feature levels on both sides.

Main entry points: [`otp_server/app/Http/Controllers/Api`](https://github.com/emran025/super_admin_agent_app/tree/main/otp_server/app/Http/Controllers/Api) (API Surface), [`super_admin_agent_app/lib/presentation`](https://github.com/emran025/super_admin_agent_app/tree/main/super_admin_agent_app/lib/presentation) (Presentation), [`super_admin_agent_app/lib/domain`](https://github.com/emran025/super_admin_agent_app/tree/main/super_admin_agent_app/lib/domain) (Domain), [`super_admin_agent_app/lib/main.dart`](https://github.com/emran025/super_admin_agent_app/blob/main/super_admin_agent_app/lib/main.dart) (App Shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_governance["Governance"]
  node_agent_constitution["Constitution<br/>policy<br/>[00_axioms.md]"]
  node_agent_architecture["Arch Rules<br/>policy"]
  node_agent_domains["Domain Contracts<br/>policy<br/>[domain_boundary.md]"]
  node_agent_security["Security Rules<br/>policy"]
  node_agent_outputs["Output Control<br/>policy<br/>[allowed_outputs.md]"]
end

subgraph group_mobile["Mobile Agent"]
  node_app_shell["App Shell<br/>flutter entrypoint<br/>[main.dart]"]
  node_presentation_layer["Presentation<br/>ui layer"]
  node_domain_layer["Domain<br/>use cases"]
  node_data_layer["Data<br/>adapters"]
  node_shared_services["Shared Core<br/>security infra"]
  node_pairing_feature{{"Pairing<br/>trust workflow"}}
  node_auth_feature{{"Push 2FA<br/>challenge workflow"}}
  node_otp_feature{{"OTP Gateway<br/>sms workflow"}}
  node_payment_feature{{"Payment Obs.<br/>event workflow"}}
  node_ws_router["WS Router<br/>messaging infra"]
  node_android_security["Device Services<br/>device infra"]
end

subgraph group_backend["OTP Server"]
  node_api_surface["API Surface<br/>http controllers"]
  node_server_services["Server Services<br/>orchestration"]
  node_server_state[("Server State<br/>models<br/>[Agent.php]")]
  node_testbed_web["Testbed Web<br/>operator ui"]
  node_events_broadcast(("Events/Realtime<br/>async coordination"))
end

subgraph group_delivery["Delivery"]
  node_ci_cd["CI/CD<br/>automation<br/>[ci.yml]"]
end

node_agent_constitution -->|"guides"| node_agent_architecture
node_agent_architecture -->|"scopes"| node_agent_domains
node_agent_security -->|"guards"| node_agent_domains
node_agent_outputs -->|"constrains"| node_agent_security
node_agent_constitution -->|"governs"| node_presentation_layer
node_agent_constitution -->|"governs"| node_api_surface
node_app_shell -->|"boots"| node_presentation_layer
node_presentation_layer -->|"renders"| node_pairing_feature
node_presentation_layer -->|"renders"| node_auth_feature
node_presentation_layer -->|"renders"| node_otp_feature
node_presentation_layer -->|"renders"| node_payment_feature
node_domain_layer -->|"implements"| node_pairing_feature
node_domain_layer -->|"implements"| node_auth_feature
node_domain_layer -->|"implements"| node_otp_feature
node_domain_layer -->|"implements"| node_payment_feature
node_data_layer -->|"adapts"| node_domain_layer
node_shared_services -->|"supports"| node_domain_layer
node_ws_router -->|"routes"| node_auth_feature
node_ws_router -->|"routes"| node_otp_feature
node_ws_router -->|"routes"| node_payment_feature
node_android_security -->|"provides"| node_shared_services
node_api_surface -->|"uses"| node_server_services
node_server_services -->|"reads/writes"| node_server_state
node_api_surface -->|"emits"| node_events_broadcast
node_testbed_web -->|"exercises"| node_api_surface
node_app_shell -->|"calls"| node_api_surface
node_app_shell -->|"listens via"| node_ws_router
node_api_surface -->|"supports"| node_testbed_web
node_ci_cd -.->|"builds"| node_app_shell
node_ci_cd -.->|"deploys"| node_api_surface

click node_agent_constitution "https://github.com/emran025/super_admin_agent_app/blob/main/agent/CONSTITUTION/00_axioms.md"
click node_agent_architecture "https://github.com/emran025/super_admin_agent_app/blob/main/agent/ARCHITECTURE/clean_architecture_rules.md"
click node_agent_domains "https://github.com/emran025/super_admin_agent_app/blob/main/agent/DOMAINS/auth_2fa/domain_boundary.md"
click node_agent_security "https://github.com/emran025/super_admin_agent_app/blob/main/agent/SECURITY/signing_and_identity.md"
click node_agent_outputs "https://github.com/emran025/super_admin_agent_app/blob/main/agent/OUTPUT_CONTROL/allowed_outputs.md"
click node_app_shell "https://github.com/emran025/super_admin_agent_app/blob/main/super_admin_agent_app/lib/main.dart"
click node_presentation_layer "https://github.com/emran025/super_admin_agent_app/tree/main/super_admin_agent_app/lib/presentation"
click node_domain_layer "https://github.com/emran025/super_admin_agent_app/tree/main/super_admin_agent_app/lib/domain"
click node_data_layer "https://github.com/emran025/super_admin_agent_app/tree/main/super_admin_agent_app/lib/data"
click node_shared_services "https://github.com/emran025/super_admin_agent_app/tree/main/super_admin_agent_app/lib/shared"
click node_pairing_feature "https://github.com/emran025/super_admin_agent_app/blob/main/super_admin_agent_app/lib/domain/pairing/use_cases/complete_pairing_use_case.dart"
click node_auth_feature "https://github.com/emran025/super_admin_agent_app/blob/main/super_admin_agent_app/lib/domain/auth_2fa/use_cases/receive_auth_challenge_use_case.dart"
click node_otp_feature "https://github.com/emran025/super_admin_agent_app/blob/main/super_admin_agent_app/lib/domain/otp_gateway/use_cases/execute_sms_dispatch_use_case.dart"
click node_payment_feature "https://github.com/emran025/super_admin_agent_app/blob/main/super_admin_agent_app/lib/domain/payment_observation/use_cases/process_incoming_sms_use_case.dart"
click node_ws_router "https://github.com/emran025/super_admin_agent_app/blob/main/super_admin_agent_app/lib/shared/infrastructure/ws_message_router.dart"
click node_android_security "https://github.com/emran025/super_admin_agent_app/blob/main/super_admin_agent_app/lib/shared/infrastructure/android_keystore_signing_service.dart"
click node_api_surface "https://github.com/emran025/super_admin_agent_app/tree/main/otp_server/app/Http/Controllers/Api"
click node_server_services "https://github.com/emran025/super_admin_agent_app/tree/main/otp_server/app/Services"
click node_server_state "https://github.com/emran025/super_admin_agent_app/blob/main/otp_server/app/Models/Agent.php"
click node_testbed_web "https://github.com/emran025/super_admin_agent_app/tree/main/otp_server/app/Http/Controllers/Web"
click node_events_broadcast "https://github.com/emran025/super_admin_agent_app/blob/main/otp_server/app/Events/TwoFactorChallengeIssued.php"
click node_ci_cd "https://github.com/emran025/super_admin_agent_app/blob/main/.github/workflows/ci.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent_constitution,node_agent_architecture,node_agent_domains,node_agent_security,node_agent_outputs toneBlue
class node_app_shell,node_presentation_layer,node_domain_layer,node_data_layer,node_shared_services,node_pairing_feature,node_auth_feature,node_otp_feature,node_payment_feature,node_ws_router,node_android_security toneAmber
class node_api_surface,node_server_services,node_server_state,node_testbed_web,node_events_broadcast toneMint
class node_ci_cd toneRose
```

## Components

### Governance

Architectural constitution, security rules, and domain contracts.

- [Constitution](https://github.com/emran025/super_admin_agent_app/blob/main/agent/CONSTITUTION/00_axioms.md): policy · Core architectural axioms, roles, failure definitions, and change policy. · `agent/CONSTITUTION/00_axioms.md`
- [Arch Rules](https://github.com/emran025/super_admin_agent_app/blob/main/agent/ARCHITECTURE/clean_architecture_rules.md): policy · Clean architecture, dependency direction, and isolation principles. · `agent/ARCHITECTURE/clean_architecture_rules.md`
- [Domain Contracts](https://github.com/emran025/super_admin_agent_app/blob/main/agent/DOMAINS/auth_2fa/domain_boundary.md): policy · Domain boundaries and mobile/server obligations for auth 2FA, OTP gateway, and payment observation. · `agent/DOMAINS/auth_2fa/domain_boundary.md`
- [Security Rules](https://github.com/emran025/super_admin_agent_app/blob/main/agent/SECURITY/signing_and_identity.md): policy · Signing, trust establishment, replay protection, audit logging, and revocation rules. · `agent/SECURITY/signing_and_identity.md`
- [Output Control](https://github.com/emran025/super_admin_agent_app/blob/main/agent/OUTPUT_CONTROL/allowed_outputs.md): policy · Allowed and forbidden outputs plus formatting constraints for agent behavior. · `agent/OUTPUT_CONTROL/allowed_outputs.md`

### Mobile Agent

Flutter runtime client with clean architecture layering.

- [App Shell](https://github.com/emran025/super_admin_agent_app/blob/main/super_admin_agent_app/lib/main.dart): flutter entrypoint · Flutter application entry and dependency wiring. · `super_admin_agent_app/lib/main.dart`
- [Presentation](https://github.com/emran025/super_admin_agent_app/tree/main/super_admin_agent_app/lib/presentation): ui layer · Pages, widgets, and Cubit state management for the mobile UI. · `super_admin_agent_app/lib/presentation`
- [Domain](https://github.com/emran025/super_admin_agent_app/tree/main/super_admin_agent_app/lib/domain): use cases · Entities, repositories, use cases, and value objects for business workflows. · `super_admin_agent_app/lib/domain`
- [Data](https://github.com/emran025/super_admin_agent_app/tree/main/super_admin_agent_app/lib/data): adapters · Remote data sources, DTOs, and repository implementations. · `super_admin_agent_app/lib/data`
- [Shared Core](https://github.com/emran025/super_admin_agent_app/tree/main/super_admin_agent_app/lib/shared): security infra · Canonical JSON, signing, secure storage, nonce generation, and audit logging. · `super_admin_agent_app/lib/shared`
- [Pairing](https://github.com/emran025/super_admin_agent_app/blob/main/super_admin_agent_app/lib/domain/pairing/use_cases/complete_pairing_use_case.dart): trust workflow · Scan tokens, link and unlink systems, and manage capability grants. · `super_admin_agent_app/lib/domain/pairing/use_cases/complete_pairing_use_case.dart`
- [Push 2FA](https://github.com/emran025/super_admin_agent_app/blob/main/super_admin_agent_app/lib/domain/auth_2fa/use_cases/receive_auth_challenge_use_case.dart): challenge workflow · Receive a challenge, present it, capture a decision, sign, and submit the response. · `super_admin_agent_app/lib/domain/auth_2fa/use_cases/receive_auth_challenge_use_case.dart`
- [OTP Gateway](https://github.com/emran025/super_admin_agent_app/blob/main/super_admin_agent_app/lib/domain/otp_gateway/use_cases/execute_sms_dispatch_use_case.dart): sms workflow · Receive dispatch commands, send local SMS, and report delivery status. · `super_admin_agent_app/lib/domain/otp_gateway/use_cases/execute_sms_dispatch_use_case.dart`
- [Payment Obs.](https://github.com/emran025/super_admin_agent_app/blob/main/super_admin_agent_app/lib/domain/payment_observation/use_cases/process_incoming_sms_use_case.dart): event workflow · Register sessions, parse inbound payment SMS, match to intent, and report observations. · `super_admin_agent_app/lib/domain/payment_observation/use_cases/process_incoming_sms_use_case.dart`
- [WS Router](https://github.com/emran025/super_admin_agent_app/blob/main/super_admin_agent_app/lib/shared/infrastructure/ws_message_router.dart): messaging infra · Routes websocket messages to domain-specific handlers. · `super_admin_agent_app/lib/shared/infrastructure/ws_message_router.dart`
- [Device Services](https://github.com/emran025/super_admin_agent_app/blob/main/super_admin_agent_app/lib/shared/infrastructure/android_keystore_signing_service.dart): device infra · Android keystore signing, SMS send/receive, permissions, and SMS parsing. · `super_admin_agent_app/lib/shared/infrastructure/android_keystore_signing_service.dart`

### OTP Server

Laravel backend authority for pairing, commands, trust verification, and reporting.

- [API Surface](https://github.com/emran025/super_admin_agent_app/tree/main/otp_server/app/Http/Controllers/Api): http controllers · Agent heartbeat, reports, pairing, OTP commands, and push challenge endpoints. · `otp_server/app/Http/Controllers/Api`
- [Server Services](https://github.com/emran025/super_admin_agent_app/tree/main/otp_server/app/Services): orchestration · Canonical JSON, encryption, signature verification, OTP dispatch, and 2FA orchestration. · `otp_server/app/Services`
- [Server State](https://github.com/emran025/super_admin_agent_app/blob/main/otp_server/app/Models/Agent.php): models · Agents, external systems, OTP dispatches, challenges, nonces, and users. · `otp_server/app/Models/Agent.php`
- [Testbed Web](https://github.com/emran025/super_admin_agent_app/tree/main/otp_server/app/Http/Controllers/Web): operator ui · Manual flows for pairing, push 2FA, SMS gateway, and the general hub. · `otp_server/app/Http/Controllers/Web`
- [Events/Realtime](https://github.com/emran025/super_admin_agent_app/blob/main/otp_server/app/Events/TwoFactorChallengeIssued.php): async coordination · Challenge and command events with broadcasting and queue-backed live updates. · `otp_server/app/Events/TwoFactorChallengeIssued.php`

### Delivery

CI and deployment workflows for the repository.

- [CI/CD](https://github.com/emran025/super_admin_agent_app/blob/main/.github/workflows/ci.yml): automation · Repository workflows for continuous integration and server deployment. · `.github/workflows/ci.yml`

## Connections

- Constitution → Arch Rules: guides · Architectural axioms constrain implementation rules.
- Arch Rules → Domain Contracts: scopes · Architecture rules apply across domain boundaries.
- Security Rules → Domain Contracts: guards · Security policy defines trust and replay constraints per domain.
- Output Control → Security Rules: constrains · Allowed outputs reinforce secure behavior.
- Constitution → Presentation: governs · Mobile code must follow the constitution.
- Constitution → API Surface: governs · Backend behavior is also bounded by the canonical policy.
- App Shell → Presentation: boots · Flutter entrypoint loads UI composition.
- Presentation → Pairing: renders · UI exposes pairing and linked-system management.
- Presentation → Push 2FA: renders · UI presents push 2FA challenge flows.
- Presentation → OTP Gateway: renders · UI supports OTP gateway workflows.
- Presentation → Payment Obs.: renders · UI supports payment observation workflows.
- Domain → Pairing: implements · Use cases define trust-linking behavior.
- Domain → Push 2FA: implements · Use cases define push 2FA behavior.
- Domain → OTP Gateway: implements · Use cases define OTP dispatch behavior.
- Domain → Payment Obs.: implements · Use cases define payment observation behavior.
- Data → Domain: adapts · Repositories and DTOs back domain contracts.
- Shared Core → Domain: supports · Core cryptographic and persistence services are consumed by use cases.
- WS Router → Push 2FA: routes · Auth websocket messages are dispatched to the 2FA flow.
- WS Router → OTP Gateway: routes · OTP websocket messages are dispatched to the gateway flow.
- WS Router → Payment Obs.: routes · Payment observation messages are dispatched to parsing/reporting.
- Device Services → Shared Core: provides · Device-side keystore, SMS, permissions, and parsing underpin shared security.
- API Surface → Server Services: uses · Controllers orchestrate service logic.
- Server Services → Server State: reads/writes · Services persist and verify trust state.
- API Surface → Events/Realtime: emits · API flows trigger realtime and asynchronous events.
- Testbed Web → API Surface: exercises · Operator test flows drive the same backend capabilities.
- App Shell → API Surface: calls · Agent communicates with backend APIs for pairing, challenges, reports, and dispatches.
- App Shell → WS Router: listens via · Real-time events are received over websocket routing.
- API Surface → Testbed Web: supports · Backend exposes manual validation flows.
- CI/CD → App Shell: builds · CI validates the Flutter application.
- CI/CD → API Surface: deploys · Deployment workflow targets the Laravel server.
