> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/marcosfabricio3/simple-manager-mobile/llms.txt
> Use this file to discover all available pages before exploring further.
# Data Flow
> How data moves through Simple Manager Mobile's architecture layers
## Data Flow Overview
Data flows through the application in a unidirectional pattern, ensuring predictable behavior and making the system easier to reason about.
## Flow Diagram
```mermaid theme={null}
sequenceDiagram
participant UI as UI Component
participant Hook as Custom Hook
participant Service as Service Layer
participant Repo as Repository
participant DB as SQLite Database
UI->>Hook: User action (e.g., create record)
Hook->>Service: create(title, type)
Service->>Service: Generate UUID & timestamps
Service->>Repo: create(record)
Repo->>DB: INSERT INTO records
DB-->>Repo: Success
Repo-->>Service: Success
Service-->>Hook: Return created record
Hook->>Service: list() to refresh
Service->>Repo: findAll()
Repo->>DB: SELECT * FROM records
DB-->>Repo: Result rows
Repo-->>Service: Record[]
Service-->>Hook: Record[]
Hook->>Hook: setState(records)
Hook-->>UI: Updated records
UI->>UI: Re-render with new data
```
## Data Flow Patterns
### Create Operation
User fills a form and submits in the UI component
UI component calls the `create()` method from `useRecords` hook
Service generates UUID, timestamps, and creates Record entity
Repository executes SQL INSERT statement
SQLite stores the record
Hook reloads data and updates component state
Component re-renders with updated data
### Read Operation
Component mounts and hook's `useEffect` runs
Hook calls `load()` which invokes `service.list()`
Repository executes `SELECT * FROM records WHERE isDeleted = 0`
Repository maps database rows to Record entities
Hook updates local state with records
Component renders the list of records
### Update Operation
User modifies a record and saves changes
UI calls `update(record)` from hook
Service updates the `updatedAt` timestamp
Repository executes SQL UPDATE statement
Hook reloads all records to reflect changes
UI updates with modified data
### Delete Operation (Soft Delete)
User confirms deletion
UI calls `remove(id)` from hook
Service calls repository's `softDelete(id)`
Repository sets `isDeleted = 1` via UPDATE query
Hook reloads records (deleted ones are filtered out)
Component re-renders without the deleted record
## Complete Example: Creating a Record
Let's trace a complete data flow for creating a new record:
### 1. UI Component (Presentation Layer)
```tsx src/presentation/screens/RecordsScreen.tsx theme={null}
import { useRecords } from '@/src/presentation/hooks/useRecords';
export function RecordsScreen() {
const { records, create } = useRecords();
const [title, setTitle] = useState('');
const handleCreate = async () => {
try {
// Step 1: Call hook's create method
await create(title, 'client');
setTitle(''); // Clear input
} catch (error) {
alert(error.message);
}
};
return (
{records.map(record => )}
);
}
```
### 2. Custom Hook (Presentation Layer)
```typescript src/presentation/hooks/useRecords.ts theme={null}
import { RecordService } from '@/src/application/services/RecordService';
export function useRecords() {
const service = useMemo(() => new RecordService(), []);
const [records, setRecords] = useState([]);
const load = async () => {
// Step 6: Reload data after creation
const data = await service.list();
setRecords(data); // Step 7: Update state
};
const create = async (title: string, type: string) => {
// Step 2: Forward to service
await service.create(title, type);
await load(); // Step 5: Refresh after creation
};
return { records, create, load };
}
```
### 3. Service (Application Layer)
```typescript src/application/services/RecordService.ts theme={null}
import { RecordRepository } from '@/src/infraestructure/repositories/RecordRepository';
import * as Crypto from 'expo-crypto';
export class RecordService {
private repository = new RecordRepository();
async create(title: string, type: string) {
// Step 3: Business logic - generate ID and timestamps
const now = new Date().toISOString();
const record: Record = {
id: Crypto.randomUUID(),
title,
type,
createdAt: now,
updatedAt: now,
isDeleted: false,
};
// Step 4: Delegate to repository
await this.repository.create(record);
return record;
}
}
```
### 4. Repository (Infrastructure Layer)
```typescript src/infraestructure/repositories/RecordRepository.ts theme={null}
import { db } from '../database/database';
export class RecordRepository {
async create(record: Record) {
// Step 4a: Execute SQL INSERT
await db.runAsync(
`INSERT INTO records (
id, title, subtitle, metadata, type, userId,
createdAt, updatedAt, isDeleted
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
[
record.id,
record.title,
record.subtitle ?? null,
record.metadata ?? null,
record.type,
record.userId ?? null,
record.createdAt,
record.updatedAt,
record.isDeleted ? 1 : 0,
]
);
}
}
```
### 5. Database (Infrastructure Layer)
```typescript src/infraestructure/database/database.ts theme={null}
import * as SQLite from "expo-sqlite";
// Step 4b: SQLite executes the INSERT
export const db = SQLite.openDatabaseSync("simple_manager.db");
```
## Error Handling Flow
Errors propagate upward through the layers:
```mermaid theme={null}
flowchart BT
DB[Database Error] -->|Throws| Repo[Repository]
Repo -->|Re-throws| Service[Service]
Service -->|Transforms| Hook[Hook]
Hook -->|Catches| UI[UI Component]
UI -->|Displays| User[User]
style DB fill:#f44336
style User fill:#4CAF50
```
```typescript Error Flow Example theme={null}
// 1. Database error occurs
db.runAsync(...) // Throws: "UNIQUE constraint failed"
// 2. Repository lets it bubble up
async create(record: Record) {
await db.runAsync(...); // Error propagates
}
// 3. Service might transform it
async create(title: string, type: string) {
try {
await this.repository.create(record);
} catch (error) {
// Could log or transform error here
throw error;
}
}
// 4. Hook catches and handles
const create = async (title: string, type: string) => {
try {
await service.create(title, type);
await load();
} catch (error) {
throw new Error(getErrorMessage(error));
}
};
// 5. UI displays to user
const handleCreate = async () => {
try {
await create(title, 'client');
} catch (error) {
alert(error.message); // User sees friendly message
}
};
```
## State Management
### Local Component State
* Form inputs
* Loading states
* Modal visibility
* Temporary UI state
### Hook State
* Fetched data (records list)
* Loading indicators
* Error states
### Global State (Zustand)
* User session
* App-wide settings
* Theme preferences
### Database State (Source of Truth)
* Persisted records
* User data
* Application data
The database is always the **single source of truth**. UI state is ephemeral and rebuilt from database on app restart.
## Data Refresh Strategy
The application uses a simple refresh strategy:
1. After any mutation (create, update, delete)
2. Reload all data from the database
3. Update component state
4. Trigger re-render
```typescript Refresh Pattern theme={null}
const create = async (title: string, type: string) => {
await service.create(title, type);
await load(); // Always refresh after mutation
};
const update = async (record: Record) => {
await service.update(record);
await load(); // Always refresh after mutation
};
const remove = async (id: string) => {
await service.delete(id);
await load(); // Always refresh after mutation
};
```
This strategy is simple and reliable. For larger datasets, consider implementing optimistic updates or pagination.
## Future: API Integration
When migrating to an API backend, the data flow remains similar:
```mermaid theme={null}
sequenceDiagram
participant UI as UI Component
participant Hook as Custom Hook
participant Service as Service Layer
participant HTTP as HTTP Client
participant API as Backend API
participant DB as Database
UI->>Hook: User action
Hook->>Service: create(data)
Service->>HTTP: POST /api/records
HTTP->>API: HTTP Request
API->>DB: INSERT
DB-->>API: Success
API-->>HTTP: JSON Response
HTTP-->>Service: Record
Service-->>Hook: Record
Hook-->>UI: Update state
```
Only the **Infrastructure Layer** needs to change. Services, hooks, and UI remain unchanged.
## Related Pages
Understand the architectural layers
See where each piece lives