---
title: "Data Flow"
description: "How data flows through the TraceRTM system"
keywords: [data flow, architecture, processing, flow]
---

# Data Flow

How data flows through TraceRTM from input to storage and back.

## Create Item Flow

```
User Input
    ↓
API Endpoint (POST /api/v1/items)
    ↓
Request Validation (Pydantic)
    ↓
Service Layer (ItemService.create)
    ↓
Business Logic Validation
    ↓
Repository Layer (ItemRepository.create)
    ↓
Database (PostgreSQL INSERT)
    ↓
Event Publishing (item.created)
    ↓
Response (JSON)
```

## Query Flow

```
User Request
    ↓
API Endpoint (GET /api/v1/items)
    ↓
Service Layer (ItemService.list)
    ↓
Cache Check (Redis)
    ↓
[Cache Hit] → Return Cached Data
    ↓
[Cache Miss] → Repository Query
    ↓
Database (PostgreSQL SELECT)
    ↓
Cache Store (Redis)
    ↓
Response (JSON)
```

## Update Flow

```
User Update Request
    ↓
API Endpoint (PUT /api/v1/items/{id})
    ↓
Get Existing Item
    ↓
Validate Changes
    ↓
Update Database
    ↓
Invalidate Cache
    ↓
Publish Event (item.updated)
    ↓
Response (Updated Item)
```

## Search Flow

```
Search Query
    ↓
API Endpoint (POST /api/v1/search)
    ↓
Parse Query
    ↓
Apply Filters
    ↓
Full-Text Search (PostgreSQL)
    ↓
Rank Results
    ↓
Return Results
```

## Export Flow

```
Export Request
    ↓
API Endpoint (GET /api/v1/export)
    ↓
Query All Data
    ↓
Format Data (JSON/CSV/Markdown)
    ↓
Generate File
    ↓
Store/Stream Response
```

## Event Flow

```
Action Occurs
    ↓
Service Publishes Event
    ↓
Event Bus Routes Event
    ↓
Handlers Process Event
    ├─→ Notification Service
    ├─→ Search Index Update
    ├─→ Cache Invalidation
    └─→ Webhook Delivery
```

## Related Documentation

- [Request Flow](./02a-request-flow) - HTTP request processing
- [Event System](../04-internals/05-event-system) - Event architecture
