Architecture Overview¶
This document describes the technical architecture of FormVox.
System Design¶
Hybrid Architecture¶
FormVox splits a form across the file it is created in and Nextcloud's own storage:
┌───────────────────────────────────────────────────────────────┐
│ Nextcloud │
├───────────────────────────────────────────────────────────────┤
│ ┌──────────────┐ ┌───────────────────┐ ┌─────────────────┐ │
│ │ FormVox │ │ Nextcloud Files │ │ Database │ │
│ │ App │◄►│ (.fvform: the │ │ (responses, │ │
│ │ │ │ form definition) │ │ secrets) │ │
│ └──────────────┘ └───────────────────┘ └─────────────────┘ │
│ │ ┌───────────────────┐ │
│ │ │ FormVox app data │ │
│ └─────────►│ (uploads, PDFs, │ │
│ │ branding, ODT) │ │
│ └───────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Vue.js │ │
│ │ Frontend │ │
│ └──────────────┘ │
└───────────────────────────────────────────────────────────────┘
Key Principles¶
- The file holds only the form - Questions, pages and settings live in
.fvform; its responses, secrets and respondent files do not - Native Integration - The form file still uses Nextcloud's file system, with standard permissions and sharing
- Portability - A form's definition can be copied, moved, shared like any file; a copy of a
.fvformfile starts with no responses of its own - Encryption Compatible - The
.fvformfile works with server-side and E2E encryption; the database and FormVox's app data are not covered by Nextcloud's server-side file encryption (see Security) - Converted on touch - A form created before 1.6.0 still has everything in its file; it is moved into the database and app data by a background job, or immediately the first time anything writes to it (see Where FormVox keeps data)
Components¶
Backend (PHP)¶
Located in lib/:
lib/
├── AppInfo/
│ └── Application.php # App bootstrap
├── Controller/
│ ├── PageController.php # Main page routes
│ ├── FormController.php # Form CRUD operations
│ ├── PublicController.php # Public form access
│ └── ExternalApiController.php # External API (API keys, webhooks)
├── Service/
│ └── FormService.php # Business logic
├── Store/
│ ├── FormStore.php # Binds a form's database row to its file
│ ├── ResponseStore.php # Responses, keys, counts, outbox
│ ├── SecretStore.php # Link token, password hash, API keys, webhooks
│ ├── FormFolders.php # App data: uploads, branding, template, PDFs
│ └── FormMigration.php, FormConverter.php # Moving a v1 form into the database
├── Command/
│ ├── Migrate.php, Orphans.php, Rebind.php, Unlock.php # occ formvox:*
├── Migration/
│ └── RegisterMimeType.php # MIME type registration
├── Settings/
│ ├── AdminSettings.php # Admin panel
│ └── AdminSection.php # Admin navigation
└── BackgroundJob/
├── TelemetryJob.php # Telemetry reporting
├── MigrateFormsJob.php # Moves v1 forms into the database
└── OrphanSweepJob.php # Removes forms whose file disappeared, after 30 days
Frontend (Vue.js)¶
Located in src/:
src/
├── main.js # App entry point
├── files.js # Files app integration
├── App.vue # Main component
├── views/
│ ├── FormEditor.vue # Form editing
│ ├── FormResults.vue # Results dashboard
│ └── PublicForm.vue # Public submission
├── components/
│ ├── QuestionTypes/ # Question components
│ ├── Settings/ # Settings panels
│ └── Results/ # Results components
└── store/
└── index.js # Vuex store
Build Output¶
Located in js/:
Data Flow¶
Form Creation¶
User clicks "New Form"
│
▼
┌───────────────────┐
│ Frontend creates │
│ form structure │
└───────────────────┘
│
▼
┌───────────────────┐
│ API POST request │
│ to /api/forms │
└───────────────────┘
│
▼
┌───────────────────┐
│ FormService │
│ creates .fvform │
└───────────────────┘
│
▼
┌───────────────────┐
│ File saved via │
│ Nextcloud Files │
└───────────────────┘
Response Submission¶
User submits form
│
▼
┌───────────────────┐
│ Frontend validates│
│ and sends data │
└───────────────────┘
│
▼
┌───────────────────┐
│ API POST request │
│ to /api/submit │
└───────────────────┘
│
▼
┌─────────────────────────────┐
│ ResponseStore │
│ - A v1 form is moved into │
│ the database first │
│ - Takes the form's row │
│ - Checks limits/capacity │
│ against the stored counts │
│ - Writes the response, its │
│ keys and outbox row │
└─────────────────────────────┘
Concurrent Access Handling¶
Responses, secrets and the counts behind the results page are written to the database, one form at a time: a submission takes the form's own row (held until the transaction commits), so changes to one form go one after the other, and a deadlock or lock timeout retries the whole transaction. A concurrency test runs many respondents in separate processes at the same moment to check that a form's limit and any per-option capacity hold exactly, with no response lost or duplicated.
FormVox also keeps a lock of its own per form (independent of this, see Security) so only one writer edits a form, or sends its outbox, at a time:
Lock Types¶
- FormVox's own form lock - One writer at a time (editing, settings, migrating a form into the database)
- Nextcloud's file lock - Taken whenever FormVox writes to the
.fvformfile itself
Conflict Resolution¶
- A busy form answers
503withreason: busyand aRetry-Afterheader; clients may simply retry - FormVox's own lock retries with jittered backoff until its deadline, and is taken over once its holder is gone
occ formvox:unlockfrees FormVox's own stuck lock by hand; it does not touch Nextcloud's file lock
File Format¶
See File Format for the complete .fvform JSON schema.
API Architecture¶
REST Endpoints¶
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/forms |
List user's forms |
| POST | /api/forms |
Create new form |
| GET | /api/forms/{id} |
Get form details |
| PUT | /api/forms/{id} |
Update form |
| DELETE | /api/forms/{id} |
Delete form |
| GET | /api/forms/{id}/responses |
Get responses |
| POST | /api/submit/{hash} |
Submit response |
See API Reference for complete documentation.
Security Architecture¶
Authentication¶
- Internal API: Nextcloud session authentication
- Public forms: Hash-based access with optional password
Authorization¶
Request → Middleware → Permission Check → Controller
│
▼
┌───────────────┐
│ File system │
│ permissions │
└───────────────┘
Data Validation¶
- Frontend: Vue.js validation
- Backend: PHP type checking and sanitization
- File: JSON schema validation
Performance Considerations¶
Caching¶
- Form structure: Cached in browser
- File content: Nextcloud file cache
- Results: Calculated on-demand
Scalability¶
| Scenario | Performance |
|---|---|
| Small forms (<100 responses) | Instant |
| Medium forms (100-1000) | Fast |
| Large forms (1000+) | Pagination recommended |
Optimization Tips¶
- Use pagination for large result sets
- Archive old responses periodically
- Enable APCu caching in Nextcloud
Integration Points¶
Nextcloud Integration¶
- Files app - Custom file handler for
.fvform - Sharing - Uses Nextcloud sharing API
- Search - Forms searchable in Unified Search
- Activity - Form events in activity stream
External Integration¶
- External API with API-key authentication, for programmatic access (see External API)
- JSON export for data analysis
- Webhooks on response created/updated/deleted, HMAC-signed (see External API)
Development Architecture¶
Build System¶
Technologies¶
- Backend: PHP 8.1+, Nextcloud App Framework
- Frontend: Vue 3, Vuex, Nextcloud Vue components
- Build: Webpack
- Styling: SCSS, Nextcloud styles
Next Steps¶
- File Format - Complete JSON schema
- API Reference - REST API documentation
- Comparison - vs Nextcloud Forms