Reporting & Analytics

What this module does

Agency administrators and Orchid’s operations team need data visibility: how many cases are active, what is the matching velocity, what are the cycle outcomes, which forms have low completion rates. This module provides custom reports, dashboard widgets, and data exports.

Business value

Data drives agency improvement. Knowing that 40% of IPs decline a first match proposal, or that the average time from inquiry to matching is 6 weeks, helps agencies identify bottlenecks and improve their processes.

Key files

• Directoryorchid/

  • Directorymodels/

    • report.py CustomReport, FormQuestionReport, MatchingDaysReport
    • user.py DashboardSettings, DashboardWidget
  • Directoryutils/

    • reports.py 112 KB — nearly all reporting logic lives here
  • Directoryapi/

    • reports.py 16 KB — reports API
    • reports_generator.py 7 KB — custom report generation API
  • Directoryviews/

    • reports.py 16 KB — reports UI
    • reports_generator.py 12 KB — custom report builder UI

reports.py utils is 112 KB

orchid/utils/reports.py is the largest utility file in the codebase. It grew organically over years and has minimal internal documentation. Most logic is raw SQLAlchemy queries or raw SQL. Use grep/text search to find specific report logic.

Report types

Pre-built reports (views at /reports)

Standard reports that all agencies have access to:

• Active cases summary
• Matching pipeline report
• Cycle outcome tracking
• Form completion rates
• Donor/carrier pipeline status

These are generated from orchid/utils/reports.py functions called by orchid/views/reports.py.

Custom reports (CustomReport)

Agency staff can build custom reports using the report generator at /reports/generator. These are saved as CustomReport records with:

• Selected data fields
• Filter criteria
• Sort order
• Optionally scheduled for regular export

Dashboard widgets

Each admin can customize their dashboard with widgets. DashboardWidget stores the widget type and configuration; DashboardSettings stores the layout (which widgets are in which position).

Widget types include: case counts by status, pending tasks, recent activity, upcoming medical events, etc.

Specialized reports

• FormQuestionReport — aggregates answers to specific form questions across many submissions (useful for analyzing intake patterns)
• MatchingDaysReport — tracks how many days cases spend in each matching stage

Excel exports

Reports can be exported as Excel files via XlsxWriter. The export logic is primarily in orchid/utils/reports.py and orchid/api/reports_generator.py.

Export files are either:

• Streamed directly to the browser as a download
• Stored in S3 and linked for later download

PostHog analytics

Product usage analytics (page views, feature usage) are tracked via PostHog. Configuration is in orchid/utils/posthog_config.py. PostHog events fire in the after_request hook of flaskapp.py.

PostHog is for Orchid’s own product analytics, not for agency-level reporting. Agencies see their own data in the reports module; Orchid’s team sees cross-agency product metrics in PostHog.

Gotchas

Most report logic is undocumented SQL

utils/reports.py (112 KB) contains years of accumulated report logic with minimal comments. Before adding a new report, search this file — there is a good chance a similar query already exists that you can adapt.

DashboardWidget config is JSON

Widget configuration is stored as a JSON blob in the DashboardWidget model. There is no schema validation — if the JSON structure changes without a migration, existing widgets may fail silently.