Version: Draft 0.1
Date: July 8, 2026
Application Name: Fieldwork
Document Status: Working Draft
Fieldwork is a web-based application for managing field survey projects, assigning field teams, creating participant surveys, distributing survey invitations, collecting public survey responses, and reviewing fieldwork progress.
The application supports both authenticated internal users and unauthenticated survey participants. Internal users manage projects, teams, permissions, invitations, and reporting. Participants access a survey through a token-scoped public invitation link, QR code, SMS link, or email link.
The application shall:
- Provide a centralized workspace for managing field research projects.
- Allow managers to create projects, assign field teams, and track response targets.
- Allow authorized users to create, edit, publish, and archive surveys.
- Allow project staff to generate invitation links for participants.
- Allow participants to complete surveys without creating an account.
- Associate responses with the correct project, survey, invitation, and field team.
- Enforce role-based access control across internal application features.
- Support later reporting, quality review, and export of field data.
Administrators control workspace-level access and permissions.
Administrators shall be able to:
- Access all Fieldwork workspace features.
- Manage role-task permissions.
- Create and archive projects.
- Assign project members.
- Manage field teams.
- Create, edit, publish, and archive surveys.
- Create participant invitations.
- Review and export response data.
Managers control project-level operations.
Managers shall be able to:
- View assigned projects.
- Create and update project details where authorized.
- Assign project members.
- Create and manage field teams.
- Create, edit, and publish surveys.
- Create participant invitations.
- Review and export project response data.
Field leads manage field execution for assigned teams or projects.
Field leads shall be able to:
- View assigned projects.
- View assigned field teams.
- Create participant invitations where authorized.
- Review response progress for assigned projects or teams.
- Export response data if granted permission.
Team members participate in field execution but have limited administrative control.
Team members shall be able to:
- View assigned projects.
- View assigned field team information.
- View survey materials relevant to field execution.
- Use authorized invitation workflows if explicitly permitted.
Participants are external users who complete surveys through public invitation access.
Participants shall be able to:
- Open a valid invitation link or QR code.
- View the published survey associated with the invitation.
- Submit survey responses.
- Receive the configured completion message after submission.
Participants shall not require an authenticated account.
The application shall support workspaces as the top-level organizational boundary.
Each workspace shall include:
- Workspace name.
- Workspace slug.
- Creator user.
- Workspace memberships.
- Workspace-level administrators.
- Workspace-specific role-task permissions.
The application shall allow authorized users to create and manage fieldwork projects.
Each project shall include:
- Project name.
- Client name.
- Location label.
- Description.
- Status.
- Response target.
- Close date.
- Creator.
- Workspace association.
Project statuses shall include:
The application shall prevent invalid project states, including:
- Empty project names.
- Empty client names.
- Non-positive response targets.
- Invalid status values.
The application shall allow authorized users to assign internal users to projects.
Each project membership shall include:
- Project.
- User.
- Project role.
- Assigning user.
- Created timestamp.
Supported project roles shall include:
- Manager.
- Field lead.
- Team member.
The application shall prevent duplicate project memberships for the same user and project.
The application shall allow authorized users to create and manage field teams inside a project.
Each field team shall include:
- Team name.
- Project association.
- Lead user.
- Status.
- Created timestamp.
- Updated timestamp.
Field team statuses shall include:
- New.
- On pace.
- Needs attention.
- Ahead.
- Closed.
The application shall ensure that:
- A field team belongs to exactly one project.
- A field team cannot be moved to a different project after creation.
- A field team lead must be a manager or field lead on the same project.
- Field team members must already have project membership for the related project.
The application shall allow authorized users to assign project members to field teams.
Each field team membership shall include:
- Field team.
- User.
- Assigning user.
- Created timestamp.
The application shall prevent duplicate team memberships for the same user and field team.
Authorized users shall be able to create surveys within a project.
Each survey shall include:
- Project association.
- Survey name.
- Completion message.
- Version.
- Status.
- Creator.
- Published timestamp.
- Created timestamp.
- Updated timestamp.
Survey statuses shall include:
- Draft.
- Published.
- Archived.
A survey shall begin in draft status unless otherwise specified.
Authorized users shall be able to edit draft surveys.
Editable survey elements shall include:
- Survey name.
- Completion message.
- Survey questions.
- Question order.
- Question prompt.
- Question type.
- Required flag.
- Question configuration.
Published surveys should not be destructively edited in a way that invalidates existing responses. If changes are required after publication, the application should either create a new version or apply controlled edits that preserve response integrity.
Authorized users shall be able to publish a survey.
The application shall enforce the following before publication:
- Survey has a non-empty name.
- Survey has valid question definitions.
- Survey status becomes
published.
- Published timestamp is set.
Only published surveys may accept participant responses.
Authorized users shall be able to archive surveys that should no longer collect responses.
Archived surveys shall remain available for historical review and reporting, but shall not accept new participant responses.
The application shall support the following question types:
- Rating.
- Single select.
- Multi select.
- Free text.
- Consent.
Each question shall include:
- Survey association.
- Ordinal position.
- Question type.
- Prompt.
- Required flag.
- Configuration JSON.
- Created timestamp.
- Updated timestamp.
The application shall ensure that:
- Question ordinal values are positive.
- Question prompts are not empty.
- Question types are limited to supported values.
- Question order is unique within a survey.
¶ 6. Invitation and Participant Access Requirements
Authorized users shall be able to create invitations for a project survey.
Each invitation shall include:
- Project.
- Survey.
- Optional field team.
- Hashed token.
- Delivery channel.
- Optional recipient email.
- Optional recipient phone.
- Optional audience label.
- Optional message body.
- Optional maximum completion count.
- Open count.
- Completion count.
- Last opened timestamp.
- Optional expiration timestamp.
- Optional revoked timestamp.
- Creating user.
- Created timestamp.
- Updated timestamp.
Supported delivery channels shall include:
- QR code.
- SMS.
- Email.
- Shareable link.
The application shall require:
- Recipient email when delivery channel is email.
- Recipient phone when delivery channel is SMS.
- Positive max completion count when max completion count is provided.
Participants shall access surveys through a public invitation route containing a token.
The application shall:
- Validate the invitation token.
- Resolve the associated project and survey.
- Confirm the survey is published.
- Confirm the invitation has not expired.
- Confirm the invitation has not been revoked.
- Confirm the invitation has not exceeded its completion limit.
- Display the participant survey without requiring login.
The application shall support QR code generation for invitation access.
QR codes shall encode a public survey invitation URL.
Users shall be able to preview or distribute QR codes for field collection.
¶ 6.4 Link, SMS, and Email Access
The application shall support link-based access for:
- Manual sharing.
- SMS delivery.
- Email delivery.
The application may initially generate the link without directly sending SMS or email. Direct delivery integrations may be added later.
Authorized users shall be able to revoke an invitation.
Revoked invitations shall not allow further survey access or response submission.
Invitations may include an expiration timestamp.
Expired invitations shall not allow further survey access or response submission.
Invitations may include a maximum completion count.
When the maximum completion count is reached, the invitation shall not accept additional responses.
Participants shall be able to submit responses to a valid public survey invitation.
Each survey response shall include:
- Invitation.
- Project.
- Survey.
- Optional field team.
- Submitted timestamp.
- Response metadata.
Each answer shall include:
- Response.
- Question.
- Answer value as JSON.
- Created timestamp.
The application shall ensure that:
- The response invitation exists.
- The invitation is not revoked.
- The invitation is not expired.
- The invitation has not exceeded its completion limit.
- The response project, survey, and field team match the invitation context.
- The survey is published.
- Each answer belongs to a question on the same survey as the response.
- Each response contains valid answers for required questions.
When a valid response is accepted, the application shall increment the invitation completion count.
The application should also support dashboard metrics derived from collected responses, including:
- Total responses.
- Response target progress.
- Responses by day.
- Responses by field team.
- Completion rate.
- Open invitations.
- Invitations nearing expiration.
¶ 8. Permissions and Access Control
The application shall use task-based permissions assigned by role within a workspace.
Each role-task permission shall include:
- Workspace.
- Role key.
- Task key.
- Allowed flag.
- Configuring user.
- Updated timestamp.
Supported role keys shall include:
- Administrator.
- Manager.
- Field lead.
- Team member.
- Participant.
The application shall support permission tasks for:
- Creating projects.
- Managing teams.
- Assigning project members.
- Inviting participants.
- Editing surveys.
- Reviewing data.
- Exporting data.
- Completing public surveys.
- Configuring role-task permissions.
The backend shall enforce permissions for all protected routes.
The frontend may hide or disable unauthorized actions, but frontend behavior shall not replace backend authorization.
Protected internal routes shall require authenticated application access.
Public survey routes shall not require login, but shall require a valid invitation token.
¶ 9. Dashboard and Reporting Requirements
The application shall provide a project dashboard showing:
- Responses collected.
- Response target.
- Response progress percentage.
- Project close date.
- Field team count.
- Survey completion rate.
- Open invitations.
- Recent project activity.
The application shall display available projects with:
- Project name.
- Client name.
- Location.
- Status.
- Response count.
The application shall display field team performance, including:
- Team name.
- Lead.
- Member count.
- Response count.
- Status.
Authorized users shall be able to preview the participant survey before publication or distribution.
Authorized users shall be able to review collected response data.
The application should support future review workflows for:
- Duplicate responses.
- Incomplete responses.
- Suspicious submissions.
- Field team attribution errors.
- Manual correction notes.
Authorized users shall be able to export response data for reporting.
Export formats should include CSV initially, with additional formats optional later.
The application shall expose JSON API routes for internal application behavior and public survey completion.
The internal API shall support:
- Bootstrap current Fieldwork context.
- List and create projects.
- Manage project members.
- Manage project field teams.
- Manage field team members.
- List and create project surveys.
- Retrieve and update surveys.
- Publish surveys.
- Create project invitations.
- List and update permissions.
The public API shall support:
- Retrieving a public survey by invitation token.
- Submitting a public survey response by invitation token.
¶ 10.3 Error Handling
The API shall return clear errors for:
- Unauthorized access.
- Missing permissions.
- Invalid project, team, survey, or invitation IDs.
- Invalid invitation token.
- Expired invitation.
- Revoked invitation.
- Completion limit reached.
- Survey not published.
- Invalid survey answer payload.
- Validation failures.
The frontend shall provide a Fieldwork application shell with navigation for:
- Overview.
- Projects.
- Field teams.
- Survey.
- Invitations.
- Permissions.
The frontend shall load initial application state from the bootstrap API.
If API data is unavailable during development, the frontend may use fallback mock data, but production builds shall use real API responses.
The frontend shall notify users when actions succeed or fail, including:
- Project created.
- Field team created.
- Survey updated.
- Survey published.
- Invitation created.
- Permission updated.
- API request failed.
The public survey interface shall:
- Load survey details from the invitation token.
- Render supported question types.
- Enforce required questions.
- Submit answers to the public response endpoint.
- Display the configured completion message after submission.
- Display an appropriate error for invalid, expired, revoked, or exhausted invitations.
The application shall preserve data integrity across the following relationships:
- A project belongs to a workspace.
- Project members belong to a project.
- Field teams belong to a project.
- Field team members must also be project members.
- Survey questions belong to a survey.
- Invitations belong to a project and survey.
- Responses belong to an invitation, project, and survey.
- Answers belong to a response and a question.
- Answers must reference questions from the same survey as the response.
- Responses must match the invitation context.
The application shall:
- Store invitation tokens only as hashes.
- Validate public access through token lookup.
- Reject revoked and expired invitation access.
- Enforce completion limits.
- Require authentication for internal routes.
- Enforce backend authorization on every protected operation.
- Prevent users from assigning invalid team leads.
- Prevent team members from being assigned outside their project context.
- Avoid exposing raw invitation token hashes to frontend clients.
- Avoid accepting trusted actor headers from untrusted clients.
The application should:
- Load project dashboard data within acceptable interactive response times.
- Support efficient filtering by project, survey, team, and invitation.
- Avoid full-table scans for common dashboard and response queries.
- Paginate large response and invitation lists.
The application shall:
- Preserve submitted survey responses once accepted.
- Avoid partial response submission when answer creation fails.
- Use transactions for response and answer submission.
- Maintain accurate invitation completion counts.
¶ 14.3 Maintainability
The application shall:
- Keep frontend API bindings aligned with backend route contracts.
- Keep backend handlers organized by Fieldwork module conventions.
- Keep schema constraints aligned with application validation.
- Use shared request and response types where practical.
The frontend should:
- Use accessible labels for form controls.
- Support keyboard navigation.
- Provide readable contrast.
- Provide clear validation messages.
- Avoid relying only on color to communicate status.
The application should support current stable versions of:
- Chrome.
- Edge.
- Firefox.
- Safari.
A manager or administrator can create a project with a valid name, client name, response target, location, and close date.
The project appears in the project list and project dashboard after creation.
A manager or administrator can create a field team for a project.
A manager or field lead assigned to the project can be selected as the field team lead.
A user cannot be added to a field team unless that user is also a member of the related project.
A manager or administrator can create a survey, add valid questions, and publish the survey.
The survey cannot accept participant responses until it is published.
A manager, administrator, or authorized field lead can create a QR, SMS, email, or link invitation for a published survey.
The participant can open the public survey through the generated invitation URL.
A participant can submit answers through a valid invitation.
The response is saved with the correct project, survey, invitation, and field team context.
The invitation completion count increases after successful submission.
¶ 15.6 Invalid Invitation Handling
The public survey UI displays an error when the invitation is:
- Invalid.
- Expired.
- Revoked.
- Over its completion limit.
- Associated with an unpublished survey.
A user without the required permission cannot perform protected actions, even if the frontend route or button is manually accessed.
Authorized users can view response totals and project progress.
Authorized users can export response data for a project.
The following features are not required for the initial release unless separately prioritized:
- Native mobile application.
- Offline survey collection.
- Automated SMS delivery integration.
- Automated email delivery integration.
- Advanced survey branching logic.
- Payment processing.
- Geolocation enforcement.
- Multimedia survey answers.
- Complex analytics dashboards.
- External CRM integrations.
- Public participant account creation.
- Should published surveys be editable, versioned, or locked?
- Should QR invitations default to single-use, team-use, or unlimited-use?
- Should field team leads be allowed to export data, or only review it?
- Should response metadata include user agent, IP address, device type, and location hints?
- Should invitation open counts increment on every public survey load or only unique loads?
- Should the system support anonymous public links with no project team attribution?
- Should exported response data include participant contact fields from invitations?
- Should survey responses support draft/incomplete state, or only final submission?
- Should audit events be stored for permission changes, invitation creation, and survey publication?
- Should the public survey UI be embedded inside the main React app or served as a separate lightweight public experience?
The recommended initial release should prioritize:
- Real API binding for projects, teams, surveys, invitations, and responses.
- Participant survey access through public invitation tokens.
- Survey publishing and response validation.
- Role-task permission enforcement.
- Project dashboard metrics based on live database data.
- CSV export for collected responses.
- Removal of remaining mock data from production paths.