How emran025/super_admin_agent_app works
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: Api API Surface · presentation Presentation · domain Domain · main.dart App Shell
Components 22
Governance
Architectural constitution, security rules, and domain contracts.
- Constitution · Core architectural axioms, roles, failure definitions, and change policy.
agent/CONSTITUTION/00_axioms.md - Arch Rules · Clean architecture, dependency direction, and isolation principles.
agent/ARCHITECTURE/clean_architecture_rules.md - Domain Contracts · Domain boundaries and mobile/server obligations for auth 2FA, OTP gateway, and payment observation.
agent/DOMAINS/auth_2fa/domain_boundary.md - Security Rules · Signing, trust establishment, replay protection, audit logging, and revocation rules.
agent/SECURITY/signing_and_identity.md - Output Control · 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 · Flutter application entry and dependency wiring.
super_admin_agent_app/lib/main.dart - Presentation · Pages, widgets, and Cubit state management for the mobile UI.
super_admin_agent_app/lib/presentation - Domain · Entities, repositories, use cases, and value objects for business workflows.
super_admin_agent_app/lib/domain - Data · Remote data sources, DTOs, and repository implementations.
super_admin_agent_app/lib/data - Shared Core · Canonical JSON, signing, secure storage, nonce generation, and audit logging.
super_admin_agent_app/lib/shared - Pairing · 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 · 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 · 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. · 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 · Routes websocket messages to domain-specific handlers.
super_admin_agent_app/lib/shared/infrastructure/ws_message_router.dart - Device Services · 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 · Agent heartbeat, reports, pairing, OTP commands, and push challenge endpoints.
otp_server/app/Http/Controllers/Api - Server Services · Canonical JSON, encryption, signature verification, OTP dispatch, and 2FA orchestration.
otp_server/app/Services - Server State · Agents, external systems, OTP dispatches, challenges, nonces, and users.
otp_server/app/Models/Agent.php - Testbed Web · Manual flows for pairing, push 2FA, SMS gateway, and the general hub.
otp_server/app/Http/Controllers/Web - Events/Realtime · 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 · Repository workflows for continuous integration and server deployment.
.github/workflows/ci.yml
Connections 30
- 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.