# driftloom/vaeloom architecture

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

- Interactive diagram: https://gitdiagram.com/driftloom/vaeloom
- Repository: https://github.com/driftloom/vaeloom

## Overview

Vaeloom is a memory-first career and productivity platform for students and early-career professionals. Its main workflow is to collect user-created files and communications, parse and organize them into searchable memory, then use scoped agents to surface useful information and support career tasks such as resume tailoring and job applications. The API also provides orchestration, model access, and enterprise controls. Some major capabilities are documented in the README but their runtime wiring was not sampled, so those links are shown as unverified rather than asserted as direct calls.

Main entry points: [`apps/api/src/api/ingestion/pipeline.py`](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/ingestion/pipeline.py) (Document Ingestion), [`apps/api/src/api/main.py`](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/main.py) (API Backend), [`apps/api/src/api/orchestrator/routing/engine.py`](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/orchestrator/routing/engine.py) (Request Routing), [`apps/api/src/api/services/search_service.py`](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/services/search_service.py) (Hybrid Search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_web["Web App"]
  node_api["API Backend<br/>[main.py]"]
end

subgraph group_knowledge["Knowledge Pipeline"]
  node_ingest["Document Ingestion<br/>[pipeline.py]"]
  node_parsers["Content Parsers<br/>[parsers.py]"]
  node_chunking["Chunking<br/>[chunking.py]"]
  node_dedup["Deduplication<br/>[dedup.py]"]
  node_memory["Memory Service<br/>[memory_service.py]"]
  node_knowledge_graph["Knowledge Graph"]
  node_search["Hybrid Search<br/>[search_service.py]"]
end

subgraph group_intelligence["Intelligence"]
  node_orchestrator["Request Routing<br/>[engine.py]"]
  node_capabilities["Agent Capabilities"]
  node_policy["Agent Policy<br/>[engine.py]"]
  node_agent_runtime["Agent Runtime<br/>[agent_runtime.py]"]
  node_llm["Model Service<br/>[llm_service.py]"]
end

subgraph group_career["Career Workflows"]
  node_resume["Resume Service<br/>[resume_service.py]"]
  node_applications["Applications"]
  node_opportunities["Opportunity Matching"]
end

subgraph group_platform["Platform Services"]
  node_database[("Relational Store<br/>[database.py]")]
  node_schema["Domain Records<br/>[schema.py]"]
  node_enterprise["Tenant Controls<br/>[tenant.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -.->|"requests"| node_api
node_api -.->|"accepts content"| node_ingest
node_ingest -->|"parses"| node_parsers
node_ingest -->|"chunks"| node_chunking
node_ingest -->|"deduplicates"| node_dedup
node_ingest -->|"persists"| node_database
node_ingest -->|"creates records"| node_schema
node_ingest -->|"embeds content"| node_llm
node_ingest -->|"mirrors entities"| node_knowledge_graph
node_ingest -->|"stores extracted facts"| node_memory
node_memory -.->|"supports retrieval"| node_search
node_knowledge_graph -.->|"supports traversal"| node_search
node_api -.->|"searches workspace"| node_search
node_api -.->|"routes requests"| node_orchestrator
node_orchestrator -.->|"plans capabilities"| node_capabilities
node_orchestrator -.->|"plans execution"| node_agent_runtime
node_orchestrator -.->|"enforces scope"| node_policy
node_agent_runtime -.->|"uses models"| node_llm
node_api -.->|"supports resume tasks"| node_resume
node_api -.->|"tracks applications"| node_applications
node_api -.->|"matches opportunities"| node_opportunities
node_api -.->|"isolates tenants"| node_enterprise
node_database -->|"stores records"| node_schema

click node_web "https://github.com/driftloom/vaeloom/tree/master/apps/web/src/app"
click node_api "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/main.py"
click node_ingest "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/ingestion/pipeline.py"
click node_parsers "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/ingestion/parsers.py"
click node_chunking "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/ingestion/chunking.py"
click node_dedup "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/ingestion/dedup.py"
click node_memory "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/services/memory_service.py"
click node_knowledge_graph "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/services/knowledge_graph_service.py"
click node_search "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/services/search_service.py"
click node_database "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/database.py"
click node_schema "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/models/schema.py"
click node_orchestrator "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/orchestrator/routing/engine.py"
click node_capabilities "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/orchestrator/capability_registry.py"
click node_policy "https://github.com/driftloom/vaeloom/blob/master/packages/agent-policy/src/vaeloom_agent_policy/engine.py"
click node_agent_runtime "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/services/agent_runtime.py"
click node_llm "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/services/llm_service.py"
click node_resume "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/services/resume_service.py"
click node_applications "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/services/application_service.py"
click node_opportunities "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/services/opportunity_matcher.py"
click node_enterprise "https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/middleware/tenant.py"

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_api,node_user toneBlue
class node_ingest,node_parsers,node_chunking,node_dedup,node_memory,node_knowledge_graph,node_search toneAmber
class node_orchestrator,node_capabilities,node_policy,node_agent_runtime,node_llm toneMint
class node_resume,node_applications,node_opportunities toneRose
class node_database,node_schema,node_enterprise toneIndigo
```

## Components

### User Experience

- [Web App](https://github.com/driftloom/vaeloom/tree/master/apps/web/src/app): `apps/web/src/app`
- [API Backend](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/main.py): `apps/api/src/api/main.py`

### Knowledge Pipeline

- [Document Ingestion](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/ingestion/pipeline.py): `apps/api/src/api/ingestion/pipeline.py`
- [Content Parsers](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/ingestion/parsers.py): `apps/api/src/api/ingestion/parsers.py`
- [Chunking](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/ingestion/chunking.py): `apps/api/src/api/ingestion/chunking.py`
- [Deduplication](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/ingestion/dedup.py): `apps/api/src/api/ingestion/dedup.py`
- [Memory Service](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/services/memory_service.py): `apps/api/src/api/services/memory_service.py`
- [Knowledge Graph](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/services/knowledge_graph_service.py): `apps/api/src/api/services/knowledge_graph_service.py`
- [Hybrid Search](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/services/search_service.py): `apps/api/src/api/services/search_service.py`

### Intelligence

- [Request Routing](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/orchestrator/routing/engine.py): `apps/api/src/api/orchestrator/routing/engine.py`
- [Agent Capabilities](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/orchestrator/capability_registry.py): `apps/api/src/api/orchestrator/capability_registry.py`
- [Agent Policy](https://github.com/driftloom/vaeloom/blob/master/packages/agent-policy/src/vaeloom_agent_policy/engine.py): `packages/agent-policy/src/vaeloom_agent_policy/engine.py`
- [Agent Runtime](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/services/agent_runtime.py): `apps/api/src/api/services/agent_runtime.py`
- [Model Service](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/services/llm_service.py): `apps/api/src/api/services/llm_service.py`

### Career Workflows

- [Resume Service](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/services/resume_service.py): `apps/api/src/api/services/resume_service.py`
- [Applications](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/services/application_service.py): `apps/api/src/api/services/application_service.py`
- [Opportunity Matching](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/services/opportunity_matcher.py): `apps/api/src/api/services/opportunity_matcher.py`

### Platform Services

- [Relational Store](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/database.py): `apps/api/src/api/database.py`
- [Domain Records](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/models/schema.py): `apps/api/src/api/models/schema.py`
- [Tenant Controls](https://github.com/driftloom/vaeloom/blob/master/apps/api/src/api/middleware/tenant.py): `apps/api/src/api/middleware/tenant.py`

### Other components

- **User**

## Connections

- User → Web App: uses (evidence: `README.md`)
- Web App → API Backend: requests
- API Backend → Document Ingestion: accepts content
- Document Ingestion → Content Parsers: parses (evidence: `apps/api/src/api/ingestion/pipeline.py`)
- Document Ingestion → Chunking: chunks (evidence: `apps/api/src/api/ingestion/pipeline.py`)
- Document Ingestion → Deduplication: deduplicates (evidence: `apps/api/src/api/ingestion/pipeline.py`)
- Document Ingestion → Relational Store: persists (evidence: `apps/api/src/api/ingestion/pipeline.py`)
- Document Ingestion → Domain Records: creates records (evidence: `apps/api/src/api/ingestion/pipeline.py`)
- Document Ingestion → Model Service: embeds content (evidence: `apps/api/src/api/ingestion/pipeline.py`)
- Document Ingestion → Knowledge Graph: mirrors entities (evidence: `apps/api/src/api/ingestion/pipeline.py`)
- Document Ingestion → Memory Service: stores extracted facts (evidence: `apps/api/src/api/ingestion/pipeline.py`)
- Memory Service → Hybrid Search: supports retrieval
- Knowledge Graph → Hybrid Search: supports traversal (evidence: `README.md`)
- API Backend → Hybrid Search: searches workspace (evidence: `README.md`)
- API Backend → Request Routing: routes requests
- Request Routing → Agent Capabilities: plans capabilities (evidence: `README.md`)
- Request Routing → Agent Runtime: plans execution (evidence: `README.md`)
- Request Routing → Agent Policy: enforces scope (evidence: `README.md`)
- Agent Runtime → Model Service: uses models (evidence: `README.md`)
- API Backend → Resume Service: supports resume tasks (evidence: `README.md`)
- API Backend → Applications: tracks applications (evidence: `README.md`)
- API Backend → Opportunity Matching: matches opportunities (evidence: `README.md`)
- API Backend → Tenant Controls: isolates tenants (evidence: `README.md`)
- Relational Store → Domain Records: stores records (evidence: `apps/api/src/api/database.py`)