Data Flow Analysis

Purpose

Answers: What does this flow actually do today, and what would we need to know to modernize it? This is a concrete, technical companion to higher-level Discover artifacts — it documents a system as it exists, not a market or an opportunity.

Authoring guidance

One flow per document. Do not try to cover an entire legacy system in a single pass — break it into individual flows first.
Name sources and sinks concretely. The actual system, table, file, or API, not a vague description like “the database.”
Type every actor. Each one is either a person doing a manual step or an automated system; say which, and what they actually do.
Capture data on both sides. What comes in and what goes out, in enough detail that another engineer could find it without asking the person who wrote this document.
Constraints matter as much as the happy path. Format, timing, volume, and access requirements shape any future redesign as much as the transformation logic does.
Don’t skip Risks, Assumptions, and Modernization Notes. This section is the payoff for doing this analysis instead of just reading the code or spreadsheet directly.
Leave the Notes section genuinely open-ended. An engineer who fills it

Additional guidance continues in the full prompt below.

Quality checklist from the prompt

Every source and sink is named concretely
Every actor is identified as a Person or an Automated System
Business value is stated explicitly in Flow Summary
Constraints on inputs and outputs are captured
Overall complexity or scale is estimated, even roughly
Risks, assumptions, and modernization recommendations are present, not left blank

Example

Show a worked example of this artifact

---
ddx:
  id: example.data-flow-analysis.depositmatch
---

# Data Flow Analysis

## Flow Summary

- Process name: Manual Deposit-to-Invoice Reconciliation
- Frequency: Weekly, every Friday
- Current state: Manual
- Business value: Ensures each client's bank deposits are matched to the
  correct outstanding invoice so the firm's books close accurately and real
  collection gaps get followed up on, instead of drifting unnoticed.

## Actors

| Actor | Type | Role in This Flow |
|-------|------|--------------------|
| Bookkeeper | Person | Downloads exports, matches deposits to invoices, resolves exceptions, updates invoice status |
| Client contact | Person | Occasionally emails to clarify an ambiguous or split deposit |
| Bank export job | Automated System | Nightly job that refreshes the bank portal's downloadable deposit CSV |

## Sources and Sinks

| Direction | System or Location | What It Provides or Receives |
|-----------|---------------------|-------------------------------|
| Source | Bank portal CSV export | Weekly list of incoming deposits (date, amount, payer reference, memo) |
| Source | Accounting platform invoice export | Outstanding invoices per client (invoice ID, amount due, due date) |
| Sink | Shared reconciliation spreadsheet | Master record of which deposit matched which invoice, and reviewer notes |
| Sink | Accounting platform invoice status field | Manually flipped to "Paid" for confirmed matches |

## Data and Data Structures

| Name | Format | Direction | Key Fields / Schema Notes |
|------|--------|-----------|-----------------------------|
| `bank_deposits.csv` | File (CSV) | Input | `date`, `amount`, `payer_ref`, `memo`; column order has changed without notice when the bank updated its export tool |
| `invoices_export.xlsx` | File (Excel) | Input | `invoice_id`, `client_id`, `amount_due`, `due_date` |
| `reconciliation-tracker.xlsx` | Spreadsheet | Output | One row per deposit: `deposit_id`, `matched_invoice_id`, `status`, `reviewer`, `notes`; layout differs per client, no canonical template |
| Invoice status field | UI field (accounting platform) | Output | Free-text-adjacent status dropdown, flipped manually per confirmed match |

## Transformations

| Step | What Happens | Performed By |
|------|---------------|--------------|
| 1 | Download the weekly bank CSV from the portal | Bookkeeper |
| 2 | Export the outstanding invoice list from the accounting platform | Bookkeeper |
| 3 | Compare deposit amount and payer name against open invoices to guess a match, then record it in the tracker spreadsheet | Bookkeeper |
| 4 | Flag ambiguous deposits (partial payments, multiple candidate invoices) in a "Needs Review" tab | Bookkeeper |
| 5 | For each confirmed match, manually set the invoice status to "Paid" in the accounting platform | Bookkeeper |

## Constraints

| Constraint | Detail |
|------------|--------|
| Format | Bank CSV column order is not contractually stable; it has silently broken spreadsheet formulas before |
| Timing | Must finish by Friday close-of-business so weekend ACH deposits don't roll into the next batch and confuse the count |
| Volume | 50-200 deposits per week per client at pilot-scale firms |
| Access | Bookkeeper needs manual read access to both the bank portal and the accounting platform; neither exposes an API today |

## Scale and Complexity

| Dimension | Assessment |
|-----------|------------|
| Manual steps | 5, all performed by one person |
| Systems touched | 3 (bank portal, accounting platform, spreadsheet) |
| Overall complexity | Medium — the per-deposit logic is simple, but volume and exception handling make it slow and error-prone |

## Risks, Assumptions, and Modernization Notes

- **Risks**: Matches are eyeballed with no audit trail of who decided what
  or why; a silent bank CSV schema change breaks spreadsheet formulas without
  warning; nothing prevents the same deposit from being matched twice.
- **Assumptions**: The bank CSV export format is stable enough to script
  against for an initial migration pass; the accounting platform will
  eventually expose an API instead of requiring a manual status flip.
- **Modernization Recommendations**: Replace manual matching with
  DepositMatch's suggested-match review queue (see
  [[product-vision]]); keep a human in the loop for exceptions, but replace
  free-form spreadsheet editing with a reviewable, audited decision log.

## Notes

Each client's spreadsheet layout is slightly different because bookkeepers
customized their own copies over time — there is no single canonical
template in use today, which will complicate any bulk import during
migration.

## Cross-References

- [[data-design]] — Design-phase target-state entity model this analysis may
  inform once a future solution is chosen.

Reference

Activity	Discover — Validate that an opportunity is worth pursuing before committing to a development cycle.
Default location	`docs/helix/00-discover/data-flow-analysis-[flow-name].md`
Requires	None
Enables	None
Informs	Data Design Feasibility Study PRD
Generation prompt	Show the full generation prompt # Data Flow Analysis Generation Prompt Document one existing business process or data flow exactly as it operates today, before any future-state solution is chosen. ## Storage Location Store at: `docs/helix/00-discover/data-flow-analysis-[flow-name].md` ## Purpose Answers: What does this flow actually do today, and what would we need to know to modernize it? This is a concrete, technical companion to higher-level Discover artifacts — it documents a system as it exists, not a market or an opportunity. ## Role Boundary Data Flow Analysis is not Data Design. Data Design documents the entity model for a system being built (Design phase, future-state). Data Flow Analysis documents an existing flow as it runs today (Discover phase, as-is), before anyone has decided what the future solution looks like. One instance covers one flow; a legacy migration effort typically produces several, one per row of a discovery inventory. ## Key Principles - One flow per document. Do not try to cover an entire legacy system in a single pass — break it into individual flows first. - Name sources and sinks concretely. The actual system, table, file, or API, not a vague description like "the database." - Type every actor. Each one is either a person doing a manual step or an automated system; say which, and what they actually do. - Capture data on both sides. What comes in and what goes out, in enough detail that another engineer could find it without asking the person who wrote this document. - Constraints matter as much as the happy path. Format, timing, volume, and access requirements shape any future redesign as much as the transformation logic does. - Don't skip Risks, Assumptions, and Modernization Notes. This section is the payoff for doing this analysis instead of just reading the code or spreadsheet directly. - Leave the Notes section genuinely open-ended. An engineer who fills it with several unprompted observations engaged with the problem; an empty Notes section on a nontrivial flow is a sign the analysis was rushed. ## Quality Checklist - [ ] Every source and sink is named concretely - [ ] Every actor is identified as a Person or an Automated System - [ ] Business value is stated explicitly in Flow Summary - [ ] Constraints on inputs and outputs are captured - [ ] Overall complexity or scale is estimated, even roughly - [ ] Risks, assumptions, and modernization recommendations are present, not left blank
Template	Show the template structure --- ddx: id: data-flow-analysis --- # Data Flow Analysis As-is documentation of one existing business process or data flow: what it does today, who and what is involved, and what would need to change to modernize it. Captured during Discover, before any future-state solution is chosen — the target-state entity model for a system being built belongs in [[data-design]] (Design phase). One instance covers one flow; a migration effort typically produces several. ## Flow Summary - Process name: [Name of the business process or flow] - Frequency: [How often this runs — daily, weekly, on-demand, event-driven] - Current state: [Manual / Automated / Hybrid] - Business value: [Why this process exists — the outcome it produces or protects] ## Actors \| Actor \| Type \| Role in This Flow \| \|-------\|------\|--------------------\| \| [Name] \| Person / Automated System \| [What they do in this flow] \| ## Sources and Sinks \| Direction \| System or Location \| What It Provides or Receives \| \|-----------\|---------------------\|-------------------------------\| \| Source \| [System, portal, or export] \| [Data provided] \| \| Sink \| [System, database, or report] \| [Data received] \| ## Data and Data Structures \| Name \| Format \| Direction \| Key Fields / Schema Notes \| \|------\|--------\|-----------\|-----------------------------\| \| [Table, file, API, or spreadsheet name] \| Table / File / API / Spreadsheet / Other \| Input / Output \| [Fields, types, or notable structure] \| ## Transformations \| Step \| What Happens \| Performed By \| \|------\|---------------\|--------------\| \| 1 \| [Processing or business logic applied to the data] \| [Actor] \| ## Constraints \| Constraint \| Detail \| \|------------\|--------\| \| Format \| [Expected shape of inputs or outputs, and how brittle it is] \| \| Timing \| [Deadlines, ordering, or freshness requirements] \| \| Volume \| [Typical and peak data volume] \| \| Access \| [What credentials, permissions, or network access this flow requires] \| ## Scale and Complexity \| Dimension \| Assessment \| \|-----------\|------------\| \| Manual steps \| [Count or description] \| \| Systems touched \| [Count or list] \| \| Overall complexity \| Low / Medium / High \| ## Risks, Assumptions, and Modernization Notes - Risks: [What's fragile, undocumented, error-prone, or likely to break] - Assumptions: [What we're taking on faith about how this flow behaves] - Modernization Recommendations: [What we'd do differently, and why] ## Notes [Freeform — anything real about this flow that doesn't fit the sections above] ## Cross-References - [[data-design]] — Design-phase target-state entity model this analysis may inform once a future solution is chosen.