# onoyima/sos-connect architecture

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

- Interactive diagram: https://gitdiagram.com/onoyima/sos-connect
- Repository: https://github.com/onoyima/sos-connect

## Overview

SOS Connect is an institution-based communications and safety product: members use web or mobile clients for chat, calls, status, and SOS, with the mobile app able to carry traffic offline over a device mesh and deliver it when connectivity returns. Institutions connect their records for sign-in and organizational sync; administrators manage membership, permissions, and platform billing. The graph preserves these documented capabilities and the sampled chat, access-control, and mesh-ingest layers. Some feature paths are represented by their controller or subsystem directory because their implementation was not excerpted.

Main entry points: [`mobile/app/_layout.tsx`](https://github.com/onoyima/sos-connect/blob/main/mobile/app/_layout.tsx) (Mobile app), [`app/Services/Chat/MessageService.php`](https://github.com/onoyima/sos-connect/blob/main/app/Services/Chat/MessageService.php) (Message service), [`app/Models/OrgUnit.php`](https://github.com/onoyima/sos-connect/blob/main/app/Models/OrgUnit.php) (Institution directory), [`app/Http/Controllers/Api/ConversationController.php`](https://github.com/onoyima/sos-connect/blob/main/app/Http/Controllers/Api/ConversationController.php) (Conversation API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Member clients"]
  node_web["Web app<br/>[app.tsx]"]
  node_mobile["Mobile app<br/>[_layout.tsx]"]
  node_chat_ui["Chat screens<br/>[&#91;id&#93;.tsx]"]
end

subgraph group_server["Application server"]
  node_api["API routes<br/>[api.php]"]
  node_chat_api["Conversation API"]
  node_message_service["Message service<br/>[MessageService.php]"]
  node_chat_data[("Conversation data<br/>[Conversation.php]")]
  node_message_data[("Message data<br/>[Message.php]")]
  node_realtime_push["Realtime and push<br/>[MessageCreated.php]"]
  node_calls["Calls<br/>[CallController.php]"]
  node_status_safety["Status and safety"]
  node_mesh_api["Mesh ingest<br/>[MeshIngest.php]"]
  node_push_job["Push delivery<br/>[SendPush.php]"]
end

subgraph group_institution["Institution operations"]
  node_records[("Institution records<br/>[Directory.php]")]
  node_connector["Records connector"]
  node_structure["Org structure<br/>[StructureSync.php]"]
  node_membership["Member access"]
  node_roles["Roles and permissions<br/>[RoleManager.php]"]
  node_org_data[("Institution directory<br/>[OrgUnit.php]")]
  node_institution_data[("Institution settings<br/>[Institution.php]")]
end

subgraph group_offline["Offline delivery"]
  node_mesh_client["Mobile mesh<br/>[MeshManager.ts]"]
  node_native_mesh["Nearby transport<br/>[index.ts]"]
  node_edge["Campus relay<br/>[index.mjs]"]
end

subgraph group_platform["Platform services"]
  node_billing["Subscriptions<br/>[Billing.php]"]
  node_billing_admin["Platform billing"]
end

node_member(("Member"))

node_member -->|"uses"| node_mobile
node_member -->|"uses"| node_web
node_mobile -->|"online requests"| node_api
node_web -.->|"API access"| node_api
node_chat_ui -.->|"renders within"| node_mobile
node_api -.->|"routes requests"| node_chat_api
node_chat_api -->|"delegates messaging"| node_message_service
node_chat_api -->|"queries conversations"| node_chat_data
node_message_service -->|"creates messages"| node_message_data
node_message_service -->|"checks conversation"| node_chat_data
node_message_service -->|"dispatches event"| node_realtime_push
node_message_service -->|"queues notifications"| node_push_job
node_mobile -->|"supports calls"| node_calls
node_mobile -->|"uses safety features"| node_status_safety
node_status_safety -->|"queues alerts"| node_push_job
node_mobile -->|"offline messaging"| node_mesh_client
node_mesh_client -->|"uses nearby transport"| node_native_mesh
node_mesh_client -.->|"optional relay"| node_edge
node_mesh_api -->|"ingests messages"| node_message_service
node_mesh_api -->|"ingests safety data"| node_status_safety
node_mobile -->|"sign-in and sync"| node_connector
node_connector -->|"reads records"| node_records
node_connector -.->|"provides directory data"| node_structure
node_structure -.->|"syncs units"| node_org_data
node_membership -->|"manages roles"| node_roles
node_membership -->|"uses areas"| node_org_data
node_roles -->|"scopes assignments"| node_org_data
node_institution_data -->|"starts trial"| node_billing
node_billing_admin -->|"manages plans"| node_billing
node_institution_data -->|"owns units"| node_org_data

click node_web "https://github.com/onoyima/sos-connect/blob/main/resources/js/app.tsx"
click node_mobile "https://github.com/onoyima/sos-connect/blob/main/mobile/app/_layout.tsx"
click node_chat_ui "https://github.com/onoyima/sos-connect/blob/main/mobile/app/chat/%5Bid%5D.tsx"
click node_api "https://github.com/onoyima/sos-connect/blob/main/routes/api.php"
click node_chat_api "https://github.com/onoyima/sos-connect/blob/main/app/Http/Controllers/Api/ConversationController.php"
click node_message_service "https://github.com/onoyima/sos-connect/blob/main/app/Services/Chat/MessageService.php"
click node_chat_data "https://github.com/onoyima/sos-connect/blob/main/app/Models/Conversation.php"
click node_message_data "https://github.com/onoyima/sos-connect/blob/main/app/Models/Message.php"
click node_realtime_push "https://github.com/onoyima/sos-connect/blob/main/app/Events/MessageCreated.php"
click node_calls "https://github.com/onoyima/sos-connect/blob/main/app/Http/Controllers/Api/CallController.php"
click node_status_safety "https://github.com/onoyima/sos-connect/blob/main/app/Http/Controllers/Api/StatusController.php"
click node_mesh_api "https://github.com/onoyima/sos-connect/blob/main/app/Services/Mesh/MeshIngest.php"
click node_records "https://github.com/onoyima/sos-connect/blob/main/connector/src/Directory.php"
click node_connector "https://github.com/onoyima/sos-connect/blob/main/app/Services/Connector/ConnectorClient.php"
click node_structure "https://github.com/onoyima/sos-connect/blob/main/app/Services/Structure/StructureSync.php"
click node_membership "https://github.com/onoyima/sos-connect/blob/main/app/Http/Controllers/Web/MemberAccessController.php"
click node_roles "https://github.com/onoyima/sos-connect/blob/main/app/Services/Access/RoleManager.php"
click node_org_data "https://github.com/onoyima/sos-connect/blob/main/app/Models/OrgUnit.php"
click node_institution_data "https://github.com/onoyima/sos-connect/blob/main/app/Models/Institution.php"
click node_mesh_client "https://github.com/onoyima/sos-connect/blob/main/mobile/src/mesh/MeshManager.ts"
click node_native_mesh "https://github.com/onoyima/sos-connect/blob/main/mobile/modules/mesh-nearby/src/index.ts"
click node_edge "https://github.com/onoyima/sos-connect/blob/main/edge-node/src/index.mjs"
click node_billing "https://github.com/onoyima/sos-connect/blob/main/app/Services/Billing/Billing.php"
click node_billing_admin "https://github.com/onoyima/sos-connect/blob/main/app/Http/Controllers/Web/PlatformBillingController.php"
click node_push_job "https://github.com/onoyima/sos-connect/blob/main/app/Jobs/SendPush.php"

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_web,node_mobile,node_chat_ui toneBlue
class node_api,node_chat_api,node_message_service,node_chat_data,node_message_data,node_realtime_push,node_calls,node_status_safety,node_mesh_api,node_push_job toneAmber
class node_records,node_connector,node_structure,node_membership,node_roles,node_org_data,node_institution_data toneMint
class node_mesh_client,node_native_mesh,node_edge toneRose
class node_billing,node_billing_admin,node_member toneIndigo
```

## Components

### Member clients

- [Web app](https://github.com/onoyima/sos-connect/blob/main/resources/js/app.tsx): `resources/js/app.tsx`
- [Mobile app](https://github.com/onoyima/sos-connect/blob/main/mobile/app/_layout.tsx): `mobile/app/_layout.tsx`
- [Chat screens](https://github.com/onoyima/sos-connect/blob/main/mobile/app/chat/%5Bid%5D.tsx): `mobile/app/chat/[id].tsx`

### Application server

- [API routes](https://github.com/onoyima/sos-connect/blob/main/routes/api.php): `routes/api.php`
- [Conversation API](https://github.com/onoyima/sos-connect/blob/main/app/Http/Controllers/Api/ConversationController.php): `app/Http/Controllers/Api/ConversationController.php`
- [Message service](https://github.com/onoyima/sos-connect/blob/main/app/Services/Chat/MessageService.php): `app/Services/Chat/MessageService.php`
- [Conversation data](https://github.com/onoyima/sos-connect/blob/main/app/Models/Conversation.php): `app/Models/Conversation.php`
- [Message data](https://github.com/onoyima/sos-connect/blob/main/app/Models/Message.php): `app/Models/Message.php`
- [Realtime and push](https://github.com/onoyima/sos-connect/blob/main/app/Events/MessageCreated.php): `app/Events/MessageCreated.php`
- [Calls](https://github.com/onoyima/sos-connect/blob/main/app/Http/Controllers/Api/CallController.php): `app/Http/Controllers/Api/CallController.php`
- [Status and safety](https://github.com/onoyima/sos-connect/blob/main/app/Http/Controllers/Api/StatusController.php): `app/Http/Controllers/Api/StatusController.php`
- [Mesh ingest](https://github.com/onoyima/sos-connect/blob/main/app/Services/Mesh/MeshIngest.php): `app/Services/Mesh/MeshIngest.php`
- [Push delivery](https://github.com/onoyima/sos-connect/blob/main/app/Jobs/SendPush.php): `app/Jobs/SendPush.php`

### Institution operations

- [Institution records](https://github.com/onoyima/sos-connect/blob/main/connector/src/Directory.php): `connector/src/Directory.php`
- [Records connector](https://github.com/onoyima/sos-connect/blob/main/app/Services/Connector/ConnectorClient.php): `app/Services/Connector/ConnectorClient.php`
- [Org structure](https://github.com/onoyima/sos-connect/blob/main/app/Services/Structure/StructureSync.php): `app/Services/Structure/StructureSync.php`
- [Member access](https://github.com/onoyima/sos-connect/blob/main/app/Http/Controllers/Web/MemberAccessController.php): `app/Http/Controllers/Web/MemberAccessController.php`
- [Roles and permissions](https://github.com/onoyima/sos-connect/blob/main/app/Services/Access/RoleManager.php): `app/Services/Access/RoleManager.php`
- [Institution directory](https://github.com/onoyima/sos-connect/blob/main/app/Models/OrgUnit.php): `app/Models/OrgUnit.php`
- [Institution settings](https://github.com/onoyima/sos-connect/blob/main/app/Models/Institution.php): `app/Models/Institution.php`

### Offline delivery

- [Mobile mesh](https://github.com/onoyima/sos-connect/blob/main/mobile/src/mesh/MeshManager.ts): `mobile/src/mesh/MeshManager.ts`
- [Nearby transport](https://github.com/onoyima/sos-connect/blob/main/mobile/modules/mesh-nearby/src/index.ts): `mobile/modules/mesh-nearby/src/index.ts`
- [Campus relay](https://github.com/onoyima/sos-connect/blob/main/edge-node/src/index.mjs): `edge-node/src/index.mjs`

### Platform services

- [Subscriptions](https://github.com/onoyima/sos-connect/blob/main/app/Services/Billing/Billing.php): `app/Services/Billing/Billing.php`
- [Platform billing](https://github.com/onoyima/sos-connect/blob/main/app/Http/Controllers/Web/PlatformBillingController.php): `app/Http/Controllers/Web/PlatformBillingController.php`

### Other components

- **Member**

## Connections

- Member → Mobile app: uses (evidence: `README.md`)
- Member → Web app: uses (evidence: `README.md`)
- Mobile app → API routes: online requests (evidence: `README.md`)
- Web app → API routes: API access
- Chat screens → Mobile app: renders within
- API routes → Conversation API: routes requests
- Conversation API → Message service: delegates messaging (evidence: `app/Http/Controllers/Api/ConversationController.php`)
- Conversation API → Conversation data: queries conversations (evidence: `app/Http/Controllers/Api/ConversationController.php`)
- Message service → Message data: creates messages (evidence: `app/Services/Chat/MessageService.php`)
- Message service → Conversation data: checks conversation (evidence: `app/Services/Chat/MessageService.php`)
- Message service → Realtime and push: dispatches event (evidence: `app/Services/Chat/MessageService.php`)
- Message service → Push delivery: queues notifications (evidence: `app/Services/Chat/MessageService.php`)
- Mobile app → Calls: supports calls (evidence: `README.md`)
- Mobile app → Status and safety: uses safety features (evidence: `README.md`)
- Status and safety → Push delivery: queues alerts (evidence: `app/Http/Controllers/Api/StatusController.php`)
- Mobile app → Mobile mesh: offline messaging (evidence: `README.md`)
- Mobile mesh → Nearby transport: uses nearby transport (evidence: `mobile/src/mesh/MeshManager.ts`)
- Mobile mesh → Campus relay: optional relay (evidence: `README.md`)
- Mesh ingest → Message service: ingests messages (evidence: `app/Services/Mesh/MeshIngest.php`)
- Mesh ingest → Status and safety: ingests safety data (evidence: `app/Services/Mesh/MeshIngest.php`)
- Mobile app → Records connector: sign-in and sync (evidence: `README.md`)
- Records connector → Institution records: reads records (evidence: `app/Services/Connector/ConnectorClient.php`)
- Records connector → Org structure: provides directory data
- Org structure → Institution directory: syncs units
- Member access → Roles and permissions: manages roles (evidence: `app/Http/Controllers/Web/MemberAccessController.php`)
- Member access → Institution directory: uses areas (evidence: `app/Http/Controllers/Web/MemberAccessController.php`)
- Roles and permissions → Institution directory: scopes assignments (evidence: `app/Services/Access/RoleManager.php`)
- Institution settings → Subscriptions: starts trial (evidence: `app/Models/Institution.php`)
- Platform billing → Subscriptions: manages plans (evidence: `app/Http/Controllers/Web/PlatformBillingController.php`)
- Institution settings → Institution directory: owns units (evidence: `app/Models/Institution.php`)
