# Data Flow Documentation

> Project Name: [Your Project Name]  
> Author(s): [Team Member Names]  
> Date: [YYYY-MM-DD]  
> Version: 1.0  

---

## User Journey Map
*Step-by-step flow of how a user moves through the app.*

### Scenario: [e.g., "New User Signs Up and Creates First Task"]

```
[Landing Page] -> [Click Sign Up] -> [Registration Form] -> [Email Verification]
-> [Dashboard] -> [Click + Add Task] -> [Task Form] -> [Task Saved + Redirect to List]
```

*(If Mermaid isn't supported, use bullet list or draw.io link)*

---

## Page/Screen Breakdown
*Document each major screen: purpose, inputs, outputs, navigation.*

### Page: `/dashboard`
- **Purpose:** Show user's task list and stats
- **UI Components:**
  - Header (user name, logout button)
  - Task list (title, due date, status badge)
  - "Add Task" floating button
- **Data Fetching:** `GET /api/tasks` on load
- **User Actions:**
  - Click task -> opens detail modal
  - Click checkbox -> updates status via `PUT /api/tasks/:id`
  - Click "Add Task" -> navigates to `/tasks/new`
- **Error States:**
  - No tasks -> show empty state illustration
  - API fails -> show retry button + toast error

*(Repeat for each major page: `/login`, `/tasks/new`, `/profile`, etc.)*

---

## API Data Flow
*How data moves between frontend, backend, and database.*

### Example: Creating a Task
```
1. User submits form on /tasks/new
2. Frontend validates input (client-side)
3. Frontend sends POST /api/tasks with JSON:
   { "title": "Study DevOps", "due_date": "2024-06-01" }
4. Backend:
   - Validates auth token
   - Sanitizes and validates input
   - Saves to database
   - Returns 201 + new task object
5. Frontend:
   - Shows success toast
   - Redirects to /dashboard with updated list
```

---

## State Management (If Applicable)
*How your app manages data across components.*

- **Local State:** Form inputs, UI toggles (use `useState`, local vars)
- **Global State:** User auth, theme (use Context, Zustand, Redux -- if needed)
- **Server State:** Tasks, user data (fetch with `useEffect` + `fetch` or React Query)

> For week-1 projects: Prefer simple local state + direct API calls. Add global state only if truly needed.

---

## Authentication Flow
*How login/session is handled.*

```
1. User enters email/password on /login
2. POST /api/auth/login -> backend verifies credentials
3. If valid: backend returns JWT token
4. Frontend stores token (httpOnly cookie or localStorage)
5. Subsequent API requests include token in Authorization header
6. Token expiry -> redirect to /login with "session expired" message
```

---

> Tips for Data Flow Docs
> - Draw simple diagrams -- even ASCII art helps!
> - Focus on user actions -> system response -> UI update
> - Note where data is validated (client AND server)
> - Keep it updated as you code -- it's a living document

---

> **Endpoint:** `/formats/dataflow-template`
> [formats](/formats) > [dataflow-template](/formats/dataflow-template)
> Up: [/formats](/formats)
> Next: [/formats/future-template](/formats/future-template)
> [Index](/)