# backend-ingress-within/ingress-within-main architecture

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

- Interactive diagram: https://gitdiagram.com/backend-ingress-within/ingress-within-main
- Repository: https://github.com/backend-ingress-within/ingress-within-main

## Overview

Ingress Within is a self-exploration and psychoeducation platform. Its principal journey is journaling, followed by background processing that surfaces patterns and reflections, builds emotional vocabulary, and supports revisiting progress through reports. The graph also preserves the documented exercise, knowledge, and psychoeducation capabilities. Source excerpts support the journal-to-queue and worker relationships; several other feature links are dashed because their implementation was not sampled.

Main entry points: [`src/lib/queue/triggers.ts`](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/queue/triggers.ts) (Processing triggers), [`src/app/api/entries/route.ts`](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/app/api/entries/route.ts) (Journal entries), [`src/lib/queue/registry.ts`](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/queue/registry.ts) (Background queue), [`src/lib/queue/workers/reflectionWorker.ts`](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/queue/workers/reflectionWorker.ts) (Reflection generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Reflective experience"]
  node_app["Application UI<br/>[App.jsx]"]
  node_journal["Journal entries<br/>[route.ts]"]
  node_session["Guided sessions<br/>[route.ts]"]
end

subgraph group_processing["Insight processing"]
  node_queue["Background queue<br/>[registry.ts]"]
  node_triggers["Processing triggers<br/>[triggers.ts]"]
  node_scoring["Entry scoring"]
  node_crisis["Crisis detection"]
  node_reflection["Reflection generation"]
  node_orchestrator["Intelligence orchestration"]
  node_knowledge["Knowledge and vocabulary"]
  node_vocab["Vocabulary engine<br/>[vocabEngine.ts]"]
  node_reports["Progress reports"]
end

subgraph group_learning["Guided learning"]
  node_exercises["Guided exercises<br/>[exerciseService.ts]"]
  node_interventions["Interventions"]
  node_modules["Psychoeducation modules"]
end

subgraph group_platform["Platform services"]
  node_ai["AI provider pipeline<br/>[factory.ts]"]
  node_database[("Supabase<br/>[db.ts]")]
  node_auth["User authentication<br/>[auth-helper.ts]"]
end

node_person(("Person"))

node_person -.->|"uses"| node_app
node_app -.->|"writes reflections"| node_journal
node_person -.->|"completes"| node_session
node_journal -->|"starts processing"| node_triggers
node_session -->|"starts processing"| node_triggers
node_triggers -->|"enqueues jobs"| node_queue
node_queue -->|"dispatches"| node_scoring
node_queue -->|"dispatches"| node_crisis
node_queue -->|"dispatches"| node_reflection
node_reflection -->|"uses provider"| node_ai
node_crisis -->|"updates job"| node_orchestrator
node_reflection -->|"updates job"| node_orchestrator
node_reflection -->|"uses knowledge"| node_knowledge
node_triggers -->|"invokes processing"| node_knowledge
node_triggers -->|"checks summaries"| node_reports
node_person -.->|"explores"| node_exercises
node_person -.->|"uses guidance"| node_interventions
node_person -.->|"learns concepts"| node_modules
node_journal -->|"reads and writes"| node_database
node_auth -->|"validates sessions"| node_database
node_journal -->|"authenticates request"| node_auth
node_session -->|"authenticates request"| node_auth
node_ai -->|"records outcomes"| node_database
node_person -.->|"builds vocabulary"| node_knowledge
node_person -.->|"reviews progress"| node_reports

click node_app "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/App.jsx"
click node_journal "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/app/api/entries/route.ts"
click node_session "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/app/api/session/route.ts"
click node_queue "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/queue/registry.ts"
click node_triggers "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/queue/triggers.ts"
click node_scoring "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/queue/workers/entryScoringWorker.ts"
click node_crisis "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/queue/workers/crisisDetectionWorker.ts"
click node_reflection "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/queue/workers/reflectionWorker.ts"
click node_orchestrator "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/orchestrator/intelligenceOrchestrator.ts"
click node_knowledge "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/knowledge/knowledgeService.ts"
click node_vocab "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/vocabEngine.ts"
click node_reports "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/weeklyReportOrchestrator.ts"
click node_exercises "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/exercises/v4/services/exerciseService.ts"
click node_interventions "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/interventions/engine/intervention-engine.ts"
click node_modules "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/modules/moduleCatalogService.ts"
click node_ai "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/ai/factory.ts"
click node_database "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/db.ts"
click node_auth "https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/auth-helper.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_app,node_journal,node_session toneBlue
class node_queue,node_triggers,node_scoring,node_crisis,node_reflection,node_orchestrator,node_knowledge,node_vocab,node_reports toneAmber
class node_exercises,node_interventions,node_modules toneMint
class node_ai,node_database,node_auth toneRose
class node_person toneIndigo
```

## Components

### Reflective experience

- [Application UI](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/App.jsx): `src/App.jsx`
- [Journal entries](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/app/api/entries/route.ts): `src/app/api/entries/route.ts`
- [Guided sessions](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/app/api/session/route.ts): `src/app/api/session/route.ts`

### Insight processing

- [Background queue](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/queue/registry.ts): `src/lib/queue/registry.ts`
- [Processing triggers](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/queue/triggers.ts): `src/lib/queue/triggers.ts`
- [Entry scoring](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/queue/workers/entryScoringWorker.ts): `src/lib/queue/workers/entryScoringWorker.ts`
- [Crisis detection](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/queue/workers/crisisDetectionWorker.ts): `src/lib/queue/workers/crisisDetectionWorker.ts`
- [Reflection generation](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/queue/workers/reflectionWorker.ts): `src/lib/queue/workers/reflectionWorker.ts`
- [Intelligence orchestration](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/orchestrator/intelligenceOrchestrator.ts): `src/lib/orchestrator/intelligenceOrchestrator.ts`
- [Knowledge and vocabulary](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/knowledge/knowledgeService.ts): `src/lib/knowledge/knowledgeService.ts`
- [Vocabulary engine](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/vocabEngine.ts): `src/lib/vocabEngine.ts`
- [Progress reports](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/weeklyReportOrchestrator.ts): `src/lib/weeklyReportOrchestrator.ts`

### Guided learning

- [Guided exercises](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/exercises/v4/services/exerciseService.ts): `src/lib/exercises/v4/services/exerciseService.ts`
- [Interventions](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/interventions/engine/intervention-engine.ts): `src/lib/interventions/engine/intervention-engine.ts`
- [Psychoeducation modules](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/modules/moduleCatalogService.ts): `src/lib/modules/moduleCatalogService.ts`

### Platform services

- [AI provider pipeline](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/ai/factory.ts): `src/lib/ai/factory.ts`
- [Supabase](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [User authentication](https://github.com/backend-ingress-within/ingress-within-main/blob/main/src/lib/auth-helper.ts): `src/lib/auth-helper.ts`

### Other components

- **Person**

## Connections

- Person → Application UI: uses
- Application UI → Journal entries: writes reflections
- Person → Guided sessions: completes
- Journal entries → Processing triggers: starts processing (evidence: `src/app/api/entries/route.ts`)
- Guided sessions → Processing triggers: starts processing (evidence: `src/app/api/session/route.ts`)
- Processing triggers → Background queue: enqueues jobs (evidence: `src/lib/queue/triggers.ts`)
- Background queue → Entry scoring: dispatches (evidence: `src/lib/queue/registry.ts`)
- Background queue → Crisis detection: dispatches (evidence: `src/lib/queue/registry.ts`)
- Background queue → Reflection generation: dispatches (evidence: `src/lib/queue/registry.ts`)
- Reflection generation → AI provider pipeline: uses provider (evidence: `src/lib/queue/workers/reflectionWorker.ts`)
- Crisis detection → Intelligence orchestration: updates job (evidence: `src/lib/queue/workers/crisisDetectionWorker.ts`)
- Reflection generation → Intelligence orchestration: updates job (evidence: `src/lib/queue/workers/reflectionWorker.ts`)
- Reflection generation → Knowledge and vocabulary: uses knowledge (evidence: `src/lib/queue/workers/reflectionWorker.ts`)
- Processing triggers → Knowledge and vocabulary: invokes processing (evidence: `src/lib/queue/triggers.ts`)
- Processing triggers → Progress reports: checks summaries (evidence: `src/lib/queue/triggers.ts`)
- Person → Guided exercises: explores (evidence: `README.md`)
- Person → Interventions: uses guidance (evidence: `README.md`)
- Person → Psychoeducation modules: learns concepts (evidence: `README.md`)
- Journal entries → Supabase: reads and writes (evidence: `src/app/api/entries/route.ts`)
- User authentication → Supabase: validates sessions (evidence: `src/lib/auth-helper.ts`)
- Journal entries → User authentication: authenticates request (evidence: `src/app/api/entries/route.ts`)
- Guided sessions → User authentication: authenticates request (evidence: `src/app/api/session/route.ts`)
- AI provider pipeline → Supabase: records outcomes (evidence: `src/lib/ai/pipeline.ts`)
- Person → Knowledge and vocabulary: builds vocabulary (evidence: `README.md`)
- Person → Progress reports: reviews progress (evidence: `README.md`)
