# advx2026/return architecture

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

- Interactive diagram: https://gitdiagram.com/advx2026/return
- Repository: https://github.com/advx2026/return

## Overview

ReTurn is a local-first personal context assistant: sampler processes gather work traces, the Apple client lets people review history, ask questions, save context and resume, and a home server stores data and performs search and AI workflows. The main daily path is capture → server ingestion → timeline/search and conversation → Save → overnight briefing → return. README documents the major product capabilities and LAN boundary; source excerpts confirm selected API, search, persistence and meeting-task links. Unsampled subsystem links are limited to documented relationships.

Main entry points: [`packages/server/src/routes.ts`](https://github.com/advx2026/return/blob/main/packages/server/src/routes.ts) (API routes), [`clients/apple/ReTurn/Core/Networking/APIClient.swift`](https://github.com/advx2026/return/blob/main/clients/apple/ReTurn/Core/Networking/APIClient.swift) (API transport), [`packages/server/src/search/query.ts`](https://github.com/advx2026/return/blob/main/packages/server/src/search/query.ts) (Hybrid search), [`packages/server/src/db/repo.ts`](https://github.com/advx2026/return/blob/main/packages/server/src/db/repo.ts) (Domain repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture"]
  node_sources["Activity sources"]
  node_sampler["Sampler runtime<br/>[index.ts]"]
  node_outbox[("Offline outbox<br/>[outbox.ts]")]
end

subgraph group_client["Apple client"]
  node_apple["Apple app<br/>[ReTurnApp.swift]"]
  node_api["API transport<br/>[APIClient.swift]"]
  node_environment["Connection setup"]
  node_timeline["Before timeline"]
  node_conversation["Now conversation<br/>[ChatStore.swift]"]
  node_after["After cards<br/>[CardsStore.swift]"]
  node_health["Health signals<br/>[HealthStore.swift]"]
end

subgraph group_server["Home server"]
  node_server["HTTP service<br/>[app.ts]"]
  node_routes["API routes<br/>[routes.ts]"]
  node_database[("SQLite store<br/>[schema.ts]")]
  node_repository["Domain repository<br/>[repo.ts]"]
end

subgraph group_intelligence["Context workflows"]
  node_search["Hybrid search<br/>[query.ts]"]
  node_chat["Chat and resume<br/>[chat.ts]"]
  node_save["Save and ferment<br/>[save.ts]"]
  node_meeting["Meeting task queue<br/>[meeting-tasks.ts]"]
  node_stats["Timeline statistics<br/>[compute.ts]"]
end

node_user(("User"))
node_models{{"Model services"}}

node_user -->|"uses"| node_apple
node_sources -->|"supplies traces"| node_sampler
node_sampler -->|"buffers offline"| node_outbox
node_sampler -->|"uploads traces"| node_server
node_apple -->|"requests data"| node_api
node_environment -->|"configures access"| node_api
node_api -->|"calls over LAN"| node_server
node_server -->|"registers routes"| node_routes
node_routes -->|"reads and writes"| node_repository
node_repository -->|"queries"| node_database
node_routes -->|"dispatches search"| node_search
node_search -->|"loads matches"| node_repository
node_routes -->|"dispatches chat"| node_chat
node_routes -->|"dispatches Save"| node_save
node_routes -->|"starts tasks"| node_meeting
node_meeting -->|"persists results"| node_repository
node_routes -->|"requests statistics"| node_stats
node_timeline -.->|"loads history"| node_api
node_conversation -.->|"sends questions"| node_api
node_after -.->|"loads suggestions"| node_api
node_health -.->|"syncs health"| node_api
node_chat -.->|"retrieves context"| node_search
node_save -->|"ferments context"| node_models
node_search -.->|"embeds queries"| node_models

click node_sources "https://github.com/advx2026/return/tree/main/packages/sampler/src/sources"
click node_sampler "https://github.com/advx2026/return/blob/main/packages/sampler/src/index.ts"
click node_outbox "https://github.com/advx2026/return/blob/main/packages/sampler/src/outbox.ts"
click node_apple "https://github.com/advx2026/return/blob/main/clients/apple/ReTurn/App/ReTurnApp.swift"
click node_api "https://github.com/advx2026/return/blob/main/clients/apple/ReTurn/Core/Networking/APIClient.swift"
click node_environment "https://github.com/advx2026/return/blob/main/clients/apple/ReTurn/Core/Networking/APIEnvironment.swift"
click node_timeline "https://github.com/advx2026/return/blob/main/clients/apple/ReTurn/Features/Timeline/Shared/Stores/TimelineStore.swift"
click node_conversation "https://github.com/advx2026/return/blob/main/clients/apple/ReTurn/Features/Home/Shared/Stores/ChatStore.swift"
click node_after "https://github.com/advx2026/return/blob/main/clients/apple/ReTurn/Features/After/Shared/CardsStore.swift"
click node_health "https://github.com/advx2026/return/blob/main/clients/apple/ReTurn/Features/Health/Shared/Stores/HealthStore.swift"
click node_server "https://github.com/advx2026/return/blob/main/packages/server/src/app.ts"
click node_routes "https://github.com/advx2026/return/blob/main/packages/server/src/routes.ts"
click node_database "https://github.com/advx2026/return/blob/main/packages/server/src/db/schema.ts"
click node_repository "https://github.com/advx2026/return/blob/main/packages/server/src/db/repo.ts"
click node_search "https://github.com/advx2026/return/blob/main/packages/server/src/search/query.ts"
click node_chat "https://github.com/advx2026/return/blob/main/packages/server/src/services/chat.ts"
click node_save "https://github.com/advx2026/return/blob/main/packages/server/src/services/save.ts"
click node_meeting "https://github.com/advx2026/return/blob/main/packages/server/src/services/meeting-tasks.ts"
click node_stats "https://github.com/advx2026/return/blob/main/packages/server/src/stats/compute.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_sources,node_sampler,node_outbox,node_user toneBlue
class node_apple,node_api,node_environment,node_timeline,node_conversation,node_after,node_health toneAmber
class node_server,node_routes,node_database,node_repository toneMint
class node_search,node_chat,node_save,node_meeting,node_stats toneRose
class node_models toneIndigo
```

## Components

### Capture

- [Activity sources](https://github.com/advx2026/return/tree/main/packages/sampler/src/sources): `packages/sampler/src/sources`
- [Sampler runtime](https://github.com/advx2026/return/blob/main/packages/sampler/src/index.ts): `packages/sampler/src/index.ts`
- [Offline outbox](https://github.com/advx2026/return/blob/main/packages/sampler/src/outbox.ts): `packages/sampler/src/outbox.ts`

### Apple client

- [Apple app](https://github.com/advx2026/return/blob/main/clients/apple/ReTurn/App/ReTurnApp.swift): `clients/apple/ReTurn/App/ReTurnApp.swift`
- [API transport](https://github.com/advx2026/return/blob/main/clients/apple/ReTurn/Core/Networking/APIClient.swift): `clients/apple/ReTurn/Core/Networking/APIClient.swift`
- [Connection setup](https://github.com/advx2026/return/blob/main/clients/apple/ReTurn/Core/Networking/APIEnvironment.swift): `clients/apple/ReTurn/Core/Networking/APIEnvironment.swift`
- [Before timeline](https://github.com/advx2026/return/blob/main/clients/apple/ReTurn/Features/Timeline/Shared/Stores/TimelineStore.swift): `clients/apple/ReTurn/Features/Timeline/Shared/Stores/TimelineStore.swift`
- [Now conversation](https://github.com/advx2026/return/blob/main/clients/apple/ReTurn/Features/Home/Shared/Stores/ChatStore.swift): `clients/apple/ReTurn/Features/Home/Shared/Stores/ChatStore.swift`
- [After cards](https://github.com/advx2026/return/blob/main/clients/apple/ReTurn/Features/After/Shared/CardsStore.swift): `clients/apple/ReTurn/Features/After/Shared/CardsStore.swift`
- [Health signals](https://github.com/advx2026/return/blob/main/clients/apple/ReTurn/Features/Health/Shared/Stores/HealthStore.swift): `clients/apple/ReTurn/Features/Health/Shared/Stores/HealthStore.swift`

### Home server

- [HTTP service](https://github.com/advx2026/return/blob/main/packages/server/src/app.ts): `packages/server/src/app.ts`
- [API routes](https://github.com/advx2026/return/blob/main/packages/server/src/routes.ts): `packages/server/src/routes.ts`
- [SQLite store](https://github.com/advx2026/return/blob/main/packages/server/src/db/schema.ts): `packages/server/src/db/schema.ts`
- [Domain repository](https://github.com/advx2026/return/blob/main/packages/server/src/db/repo.ts): `packages/server/src/db/repo.ts`

### Context workflows

- [Hybrid search](https://github.com/advx2026/return/blob/main/packages/server/src/search/query.ts): `packages/server/src/search/query.ts`
- [Chat and resume](https://github.com/advx2026/return/blob/main/packages/server/src/services/chat.ts): `packages/server/src/services/chat.ts`
- [Save and ferment](https://github.com/advx2026/return/blob/main/packages/server/src/services/save.ts): `packages/server/src/services/save.ts`
- [Meeting task queue](https://github.com/advx2026/return/blob/main/packages/server/src/services/meeting-tasks.ts): `packages/server/src/services/meeting-tasks.ts`
- [Timeline statistics](https://github.com/advx2026/return/blob/main/packages/server/src/stats/compute.ts): `packages/server/src/stats/compute.ts`

### Other components

- **User**
- **Model services**

## Connections

- User → Apple app: uses
- Activity sources → Sampler runtime: supplies traces
- Sampler runtime → Offline outbox: buffers offline (evidence: `packages/sampler/src/index.ts`)
- Sampler runtime → HTTP service: uploads traces
- Apple app → API transport: requests data
- Connection setup → API transport: configures access (evidence: `clients/apple/ReTurn/Core/Networking/APIEnvironment.swift`)
- API transport → HTTP service: calls over LAN
- HTTP service → API routes: registers routes (evidence: `packages/server/src/app.ts`)
- API routes → Domain repository: reads and writes (evidence: `packages/server/src/routes.ts`)
- Domain repository → SQLite store: queries (evidence: `packages/server/src/db/repo.ts`)
- API routes → Hybrid search: dispatches search (evidence: `packages/server/src/routes.ts`)
- Hybrid search → Domain repository: loads matches (evidence: `packages/server/src/search/query.ts`)
- API routes → Chat and resume: dispatches chat (evidence: `packages/server/src/routes.ts`)
- API routes → Save and ferment: dispatches Save (evidence: `packages/server/src/routes.ts`)
- API routes → Meeting task queue: starts tasks (evidence: `packages/server/src/app.ts`)
- Meeting task queue → Domain repository: persists results (evidence: `packages/server/src/services/meeting-tasks.ts`)
- API routes → Timeline statistics: requests statistics (evidence: `packages/server/src/routes.ts`)
- Before timeline → API transport: loads history
- Now conversation → API transport: sends questions
- After cards → API transport: loads suggestions
- Health signals → API transport: syncs health
- Chat and resume → Hybrid search: retrieves context
- Save and ferment → Model services: ferments context
- Hybrid search → Model services: embeds queries
