# yishai946/trace architecture

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

- Interactive diagram: https://gitdiagram.com/yishai946/trace
- Repository: https://github.com/yishai946/trace

## Overview

This repository provides search-and-rescue mission coordination: commanders organize missions and teams in a web console, while field searchers join missions, share location, submit reports and sightings, and raise SOS alerts. The API services persist mission activity and timeline events; the field app also presents assigned-area reports and map data. The graph highlights the sampled command and field flows plus major API capabilities visible in the source index. Many route registrations and unsampled integrations are not evidenced here, so their connections are omitted.

Main entry points: [`apps/api/src/db/index.ts`](https://github.com/yishai946/trace/blob/dev/apps/api/src/db/index.ts) (Postgres database), [`apps/api/src/modules/timeline/timeline.service.ts`](https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/timeline/timeline.service.ts) (Timeline service), [`apps/api/src/modules/missions/missions.service.ts`](https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/missions/missions.service.ts) (Mission service), [`apps/api/src/modules/participants/participants.service.ts`](https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/participants/participants.service.ts) (Participant service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_command["Command console"]
  node_launch["Console launch<br/>[Launch.tsx]"]
  node_mission_actions["Mission actions"]
  node_console_queries["Console queries"]
  node_new_mission["Mission creation"]
  node_command_map["Mission map<br/>[index.tsx]"]
end

subgraph group_field["Field app"]
  node_field_queries["Field mission queries<br/>[queries.ts]"]
  node_field_reports["Reports screen"]
  node_field_map_area["Map area data<br/>[useMapArea.ts]"]
end

subgraph group_api["API services"]
  node_api_server["API server<br/>[server.ts]"]
  node_auth["Authentication<br/>[auth.plugin.ts]"]
  node_mission_service["Mission service"]
  node_participant_service["Participant service"]
  node_polygon_service["Polygon service"]
  node_report_service["Report service<br/>[reports.service.ts]"]
  node_sighting_service["Sighting service"]
  node_sos_service["SOS service<br/>[sos.service.ts]"]
  node_tracking_service["Tracking service"]
  node_timeline_service["Timeline service"]
end

subgraph group_data["Shared data"]
  node_domain["Domain rules<br/>[index.ts]"]
  node_schemas["API schemas<br/>[index.ts]"]
end

subgraph group_runtime["Runtime infrastructure"]
  node_database[("Postgres database<br/>[index.ts]")]
  node_schema["Database schema<br/>[schema.ts]"]
end

node_commander(("Commander"))
node_searcher(("Field searcher"))

node_commander -->|"uses console"| node_launch
node_launch -.->|"offers actions"| node_mission_actions
node_mission_actions -->|"uses queries"| node_console_queries
node_commander -.->|"creates missions"| node_new_mission
node_new_mission -->|"uses queries"| node_console_queries
node_commander -.->|"manages map"| node_command_map
node_searcher -.->|"reviews reports"| node_field_reports
node_field_reports -->|"loads mission data"| node_field_queries
node_field_reports -.->|"shares report model"| node_field_map_area
node_field_map_area -->|"loads mission data"| node_field_queries
node_api_server -->|"creates connection"| node_database
node_api_server -->|"configures database"| node_schema
node_mission_service -->|"reads and writes"| node_database
node_participant_service -->|"reads and writes"| node_database
node_participant_service -->|"uses tracking rules"| node_tracking_service
node_polygon_service -->|"reads and writes"| node_database
node_report_service -->|"reads and writes"| node_database
node_report_service -->|"records events"| node_timeline_service
node_sighting_service -->|"reads and writes"| node_database
node_sos_service -->|"reads and writes"| node_database
node_sos_service -->|"records events"| node_timeline_service
node_mission_service -->|"records events"| node_timeline_service
node_polygon_service -->|"records events"| node_timeline_service
node_mission_service -->|"applies rules"| node_domain
node_participant_service -->|"applies rules"| node_domain
node_mission_service -->|"uses contracts"| node_schemas
node_report_service -->|"uses contracts"| node_schemas
node_auth -->|"resolves profiles"| node_database
node_timeline_service -->|"persists events"| node_database

click node_launch "https://github.com/yishai946/trace/blob/dev/apps/command/src/App/Launch.tsx"
click node_mission_actions "https://github.com/yishai946/trace/blob/dev/apps/command/src/App/Console/useMissionActions.ts"
click node_console_queries "https://github.com/yishai946/trace/tree/dev/apps/command/src/mission/missionQueries"
click node_new_mission "https://github.com/yishai946/trace/blob/dev/apps/command/src/pages/NewMissionPage/useNewMissionForm.ts"
click node_command_map "https://github.com/yishai946/trace/blob/dev/apps/command/src/map/MissionMap/index.tsx"
click node_field_queries "https://github.com/yishai946/trace/blob/dev/apps/field/src/mission/queries.ts"
click node_field_reports "https://github.com/yishai946/trace/blob/dev/apps/field/src/components/ReportsScreen/useReportsScreen.ts"
click node_field_map_area "https://github.com/yishai946/trace/blob/dev/apps/field/src/components/MapScreen/useMapArea.ts"
click node_api_server "https://github.com/yishai946/trace/blob/dev/apps/api/src/server.ts"
click node_auth "https://github.com/yishai946/trace/blob/dev/apps/api/src/auth/auth.plugin.ts"
click node_mission_service "https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/missions/missions.service.ts"
click node_participant_service "https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/participants/participants.service.ts"
click node_polygon_service "https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/polygons/polygons.service.ts"
click node_report_service "https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/reports/reports.service.ts"
click node_sighting_service "https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/sightings/sightings.service.ts"
click node_sos_service "https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/sos/sos.service.ts"
click node_tracking_service "https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/tracking/tracking.service.ts"
click node_timeline_service "https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/timeline/timeline.service.ts"
click node_database "https://github.com/yishai946/trace/blob/dev/apps/api/src/db/index.ts"
click node_schema "https://github.com/yishai946/trace/blob/dev/apps/api/src/db/schema.ts"
click node_domain "https://github.com/yishai946/trace/blob/dev/packages/domain/src/mission/index.ts"
click node_schemas "https://github.com/yishai946/trace/blob/dev/packages/schemas/src/index.ts"

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_launch,node_mission_actions,node_console_queries,node_new_mission,node_command_map toneBlue
class node_field_queries,node_field_reports,node_field_map_area toneAmber
class node_api_server,node_auth,node_mission_service,node_participant_service,node_polygon_service,node_report_service,node_sighting_service,node_sos_service,node_tracking_service,node_timeline_service toneMint
class node_domain,node_schemas toneRose
class node_database,node_schema,node_commander,node_searcher toneIndigo
```

## Components

### Command console

- [Console launch](https://github.com/yishai946/trace/blob/dev/apps/command/src/App/Launch.tsx): `apps/command/src/App/Launch.tsx`
- [Mission actions](https://github.com/yishai946/trace/blob/dev/apps/command/src/App/Console/useMissionActions.ts): `apps/command/src/App/Console/useMissionActions.ts`
- [Console queries](https://github.com/yishai946/trace/tree/dev/apps/command/src/mission/missionQueries): `apps/command/src/mission/missionQueries`
- [Mission creation](https://github.com/yishai946/trace/blob/dev/apps/command/src/pages/NewMissionPage/useNewMissionForm.ts): `apps/command/src/pages/NewMissionPage/useNewMissionForm.ts`
- [Mission map](https://github.com/yishai946/trace/blob/dev/apps/command/src/map/MissionMap/index.tsx): `apps/command/src/map/MissionMap/index.tsx`

### Field app

- [Field mission queries](https://github.com/yishai946/trace/blob/dev/apps/field/src/mission/queries.ts): `apps/field/src/mission/queries.ts`
- [Reports screen](https://github.com/yishai946/trace/blob/dev/apps/field/src/components/ReportsScreen/useReportsScreen.ts): `apps/field/src/components/ReportsScreen/useReportsScreen.ts`
- [Map area data](https://github.com/yishai946/trace/blob/dev/apps/field/src/components/MapScreen/useMapArea.ts): `apps/field/src/components/MapScreen/useMapArea.ts`

### API services

- [API server](https://github.com/yishai946/trace/blob/dev/apps/api/src/server.ts): `apps/api/src/server.ts`
- [Authentication](https://github.com/yishai946/trace/blob/dev/apps/api/src/auth/auth.plugin.ts): `apps/api/src/auth/auth.plugin.ts`
- [Mission service](https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/missions/missions.service.ts): `apps/api/src/modules/missions/missions.service.ts`
- [Participant service](https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/participants/participants.service.ts): `apps/api/src/modules/participants/participants.service.ts`
- [Polygon service](https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/polygons/polygons.service.ts): `apps/api/src/modules/polygons/polygons.service.ts`
- [Report service](https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/reports/reports.service.ts): `apps/api/src/modules/reports/reports.service.ts`
- [Sighting service](https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/sightings/sightings.service.ts): `apps/api/src/modules/sightings/sightings.service.ts`
- [SOS service](https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/sos/sos.service.ts): `apps/api/src/modules/sos/sos.service.ts`
- [Tracking service](https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/tracking/tracking.service.ts): `apps/api/src/modules/tracking/tracking.service.ts`
- [Timeline service](https://github.com/yishai946/trace/blob/dev/apps/api/src/modules/timeline/timeline.service.ts): `apps/api/src/modules/timeline/timeline.service.ts`

### Shared data

- [Domain rules](https://github.com/yishai946/trace/blob/dev/packages/domain/src/mission/index.ts): `packages/domain/src/mission/index.ts`
- [API schemas](https://github.com/yishai946/trace/blob/dev/packages/schemas/src/index.ts): `packages/schemas/src/index.ts`

### Runtime infrastructure

- [Postgres database](https://github.com/yishai946/trace/blob/dev/apps/api/src/db/index.ts): `apps/api/src/db/index.ts`
- [Database schema](https://github.com/yishai946/trace/blob/dev/apps/api/src/db/schema.ts): `apps/api/src/db/schema.ts`

### Other components

- **Commander**
- **Field searcher**

## Connections

- Commander → Console launch: uses console
- Console launch → Mission actions: offers actions
- Mission actions → Console queries: uses queries (evidence: `apps/command/src/App/Console/useMissionActions.ts`)
- Commander → Mission creation: creates missions
- Mission creation → Console queries: uses queries (evidence: `apps/command/src/pages/NewMissionPage/useNewMissionForm.ts`)
- Commander → Mission map: manages map
- Field searcher → Reports screen: reviews reports
- Reports screen → Field mission queries: loads mission data (evidence: `apps/field/src/components/ReportsScreen/useReportsScreen.ts`)
- Reports screen → Map area data: shares report model
- Map area data → Field mission queries: loads mission data (evidence: `apps/field/src/components/MapScreen/useMapArea.ts`)
- API server → Postgres database: creates connection (evidence: `apps/api/src/server.ts`)
- API server → Database schema: configures database
- Mission service → Postgres database: reads and writes (evidence: `apps/api/src/modules/missions/missions.service.ts`)
- Participant service → Postgres database: reads and writes (evidence: `apps/api/src/modules/participants/participants.service.ts`)
- Participant service → Tracking service: uses tracking rules (evidence: `apps/api/src/modules/participants/participants.service.ts`)
- Polygon service → Postgres database: reads and writes (evidence: `apps/api/src/modules/polygons/polygons.service.ts`)
- Report service → Postgres database: reads and writes (evidence: `apps/api/src/modules/reports/reports.service.ts`)
- Report service → Timeline service: records events (evidence: `apps/api/src/modules/reports/reports.service.ts`)
- Sighting service → Postgres database: reads and writes (evidence: `apps/api/src/modules/sightings/sightings.service.ts`)
- SOS service → Postgres database: reads and writes (evidence: `apps/api/src/modules/sos/sos.service.ts`)
- SOS service → Timeline service: records events (evidence: `apps/api/src/modules/sos/sos.service.ts`)
- Mission service → Timeline service: records events (evidence: `apps/api/src/modules/missions/missions.service.ts`)
- Polygon service → Timeline service: records events (evidence: `apps/api/src/modules/polygons/polygons.service.ts`)
- Mission service → Domain rules: applies rules (evidence: `apps/api/src/modules/missions/missions.service.ts`)
- Participant service → Domain rules: applies rules (evidence: `apps/api/src/modules/participants/participants.service.ts`)
- Mission service → API schemas: uses contracts (evidence: `apps/api/src/modules/missions/missions.service.ts`)
- Report service → API schemas: uses contracts (evidence: `apps/api/src/modules/reports/reports.service.ts`)
- Authentication → Postgres database: resolves profiles (evidence: `apps/api/src/auth/auth.plugin.ts`)
- Timeline service → Postgres database: persists events (evidence: `apps/api/src/modules/timeline/timeline.service.ts`)