> For the complete documentation index, see [llms.txt](https://fieldworker.gitbook.io/fieldworker-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fieldworker.gitbook.io/fieldworker-docs/fundamentals/concepts/information-architecture.md). # Information Architecture ## Fieldworker Information Architecture The [Fieldworker Information Architecture](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/information-architecture) is designed to create a structured, relational ecosystem that balances independent entities with highly coordinated business processes. This architecture ensures that data flows seamlessly between administrative oversight in the platform and field execution in the Ability Hub. #### Key Entities (Tables) The system is built upon several [primary entities](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/information-architecture) that can exist independently within the database: * [Customer](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/customer): The central recipient of care. A customer is a primary entity and the "anchor" for clinical and billing data. * [Employee](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/employee): The workforce of the agency. Employees are primary entities with specific roles (Admin or Caregiver) and defined manager relationships. * [Location](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/location): A validated physical address or geofence. Locations exist as primary entities to ensure [Electronic Visit Verification (EVV)](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/product-guides/electronic-visit-verification) integrity. * [Contact](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/contacts): External stakeholders (family, physicians, case managers) who form the [Circle of Care](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/circle-of-care) around a customer. * [Project](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/project): The operational "container" or contract that binds customers, employees, and locations together to authorize work. * [Task](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/task): The smallest unit of work, representing a specific visit or administrative action with a defined start and end time. #### Key Relationships The architecture relies on [specific associations](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/information-architecture) to automate business logic: * Customer - Project: A customer is the beneficiary of a project. While a customer is a standalone entity, they can be associated with [more than one project](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/information-architecture) (e.g., one for Respite Care and another for Community Habilitation). * Project - Employee/Location/Contact: The [Project](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/project) acts as a junction. It requires a customer, at least one assigned employee, and at least one [authorized location](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/information-architecture) to function. It also stores relevant [Contacts](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/contacts) for that specific service line. * Customer - Location: While locations are independent, they are mapped to customers to establish the "Home" geofence for [EVV](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/product-guides/electronic-visit-verification). * Employee - Employee: Staff members are organized hierarchically, where every employee has [one assigned manager](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/information-architecture) but can interact with many others across different project teams. #### Architecture Invariants and Constraints To maintain data integrity and regulatory compliance, the system enforces several [fundamental constraints](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/information-architecture): 1. Entity Independence: Customers, Employees, Locations, and Contacts can all [exist on their own](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/information-architecture) as primary records without being immediately linked to a project. 2. Project Requirements: A project cannot exist in a vacuum; it strictly [requires a customer, an employee, and at least a location](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/information-architecture) to be considered valid for scheduling. 3. Relational Mapping: \* A [Contact](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/contacts) may be associated with specific customers or projects to ensure HIPAA-compliant information sharing. * A [Location](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/location) must be associated with a project to be visible as a "service site" for caregivers in the Ability Hub. 4. Workforce Structure: An employee is constrained to [one manager](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/information-architecture) for administrative reporting, ensuring clear lines of accountability for [Time Management](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/product-guides/time-management). The system operates under these specific invariants and constraints: #### 1. The "Primary Entity" Invariant The most significant architectural rule is that most core objects are "Primary Entities." This means they can be created and exist in the database without being linked to any other record. * Standalone Entities: [Customer](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/customer), [Employee](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/employee), [Location](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/location), and [Contact](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/contacts) all exist as independent records. You do not need a project or a task to create them. * Operational Benefit: This allows an agency to build its "database of record" (onboarding staff and clients) before actually scheduling a single minute of care. #### 2. The Project Constraint (The Junction Rule) While other entities are independent, the [Project](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/project) is the system's most constrained entity. It acts as the mandatory "junction" for service delivery. * The "Triple-Threat" Requirement: A [Project](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/project) cannot exist or function in a vacuum. It strictly requires three specific links to be valid: 1. Exactly one [Customer](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/customer). 2. At least one [Employee](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/employee). 3. At least one [Location](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/location). * Constraint Logic: This ensures that no "ghost work" is performed. Every project must have a recipient, a provider, and a validated site for [Electronic Visit Verification (EVV)](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/product-guides/electronic-visit-verification). #### 3. Cardinality and Mapping Invariants The architecture defines how these entities can scale relative to each other: * One-to-Many Customer Projects: A single [Customer](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/customer) may be the anchor for multiple [Projects](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/project). This allows an agency to track different service lines (e.g., Physical Therapy vs. Home Habilitation) as separate financial and clinical containers for the same person. * Employee Hierarchy: An [Employee](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/employee) is constrained to having exactly one assigned manager. This is a hard invariant for administrative and payroll accountability, even though the employee can collaborate with many others in different project teams. * Flexible Contact Mapping: While a [Contact](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/contacts) is a primary entity, it can be optionally associated with either a [Customer](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/customer), a specific [Project](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/project), or both. This allows for granular control over the [Circle of Care](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/circle-of-care). #### 4. Location Scoping A [Location](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/location) is a standalone entity, but it only becomes visible to a caregiver in the Ability Hub once it is explicitly associated with a [Project](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/project). This constraint ensures that staff are only directed to authorized service sites. In the Fieldworker ecosystem, [Artifacts](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/artifacts) are the tangible, verifiable outputs produced by your agency's operations. They serve as the legal and financial proof that the constraints of a [Project](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/project) were met—specifically that an authorized [Employee](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/employee) provided a specific service to a [Customer](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/customer) at a validated [Location](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/location). #### Key System Artifacts Artifacts are generated automatically or semi-automatically as work progresses through the [Visits and Verification](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/visits-and-verification) lifecycle.
Artifact TypeGeneration SourceRegulatory/Business Purpose
TimesheetsDerived from completed Tasks and EVV logs.Used for payroll and to verify labor hours for state labor law compliance.
Case NotesAuthored by caregivers in the Ability Hub during a visit.Provides the clinical narrative required for medical necessity and quality of care audits.
837 ClaimsCompiled from verified visits within the Revenue Cycle.The standardized EDI file used to request payment from Medicaid or private Billing entities.
Completed FormsSubmitted via the mobile app as part of a Checklist.Captures structured data (like vitals or incident details) for specific clinical protocols.
ReportsAggregated from global entity data.Provides high-level visibility into agency performance, staff utilization, and budget health.
#### Artifacts as the Result of Constraints Artifacts are only "valid" if they respect the underlying [Information Architecture](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/information-architecture). Because a [Project](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/project) acts as the mandatory junction, an artifact cannot be generated unless all foundational links are present: * The Validation Gate: You cannot generate a [Timesheet](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/product-guides/time-management) artifact for an employee if they were not assigned to that specific project. This prevents "ghost billing." * The Clinical Link: A [Case Note](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/case-note) is explicitly tied to a [Task](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/task). This ensures that every clinical observation is anchored to a specific window of time and a specific customer, maintaining a clear [Patient Journal](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/patient-journal). * The Financial Anchor: A Claim artifact pulls the [Location](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/location) data from the project to populate the "Place of Service" code. If the location was not pre-authorized in the project, the system will flag the claim as "Unclean" before it is ever sent. #### Importance of Audit Readiness For agencies, artifacts are the primary defense during an audit. Since Fieldworker enforces [Invariants and Constraints](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/information-architecture) (like the "Triple-Threat" project requirement), the resulting artifacts are inherently more accurate. If a state auditor asks for proof of a visit, the platform can produce a single packet containing the EVV timestamp, the GPS coordinates, the [Case Note](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/case-note), and the signed [Form](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/forms)—all linked back to the same authorized project. The [Revenue Cycle](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/revenue-cycle) is the financial lifecycle that converts clinical effort into agency sustainability. By enforcing the [Information Architecture](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/information-architecture) constraints at every step, FieldWorker ensures that the transition from a visit to a paid claim is automated and audit-ready. #### Step 1: The Verified Visit (The Artifact) The process begins in the field. When a caregiver completes a [Task](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/task) via the [Ability Hub](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/audiences/caregivers-ability-hub), they generate the core data: * EVV Data: GPS and Timestamps prove the visit occurred at the authorized [Location](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/location). * Clinical Data: [Case Notes](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/case-note) provide the medical necessity justification required by [Billing](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/billing) entities. #### Step 2: Pre-Billing Audit (The Validation) Before a claim is created, the system "scrubs" the visit against the [Project](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/project) constraints: 1. Authorization Check: Does the visit match a valid [Prior Authorization](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/product-guides/revenue-cycle-management)? If the caregiver worked 5 hours but only 4 were authorized, the system flags the exception. 2. Constraint Match: The system verifies that the [Employee](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/employee) was assigned to the project and the [Location](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/location) is correct. This ensures the "Place of Service" code on the claim is accurate. #### Step 3: Claim Generation & Submission Once verified, the visit is bundled into a standardized 837 Claim file: * Data Integration: The claim automatically pulls the [Customer's](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/customer) Medicaid ID and the project's specific billing codes. * Batching: Verified visits are grouped into batches to be sent to different [Billing](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/billing) entities (e.g., DDD, Managed Care Organizations). #### Step 4: Reconciliation & Payment The cycle concludes when the agency receives payment: * ERA Posting: Electronic Remittance Advices (ERAs) are imported to automatically match payments to the original [Reports](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/reports). * Denial Management: If a claim is denied, the system links the denial back to the specific [Visit](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/visits-and-verification), allowing administrators to fix the data and resubmit. #### Why this Workflow is Powerful By tying financial artifacts directly to the [Information Architecture](https://app.gitbook.com/o/l66ooAirOIZbkkTyDA8V/s/FKFmA5xK4sMCcp1WP4Kc/~/edit/~/changes/682/fundamentals/concepts/information-architecture), FieldWorker eliminates "Lost Revenue." Every hour of care documented in the fieldworker is tracked until it becomes a paid claim.