App Developer Guide
App Developer Guide
App Developer Guide
Build apps that extract structured data from documents and present it through widgets. All app definitions live in the Apps table (Postgres)—no code in the repo.
How It Works
- File upload → VaultSafe analyzes it (document type, description, entities, key-value content).
- Your app’s agent prompt runs on that metadata → extracts structured data.
- Data is stored in
user_app(user_id + app_id + data). - Widget renders the data (list, table, or card view).
Security: Apps never see raw files. They only receive pre-extracted metadata.
Creating an App
1. Define Your Schema
Example (Birthdays):
{
"extraction": {
"birthdays": [
{ "person_name": "string", "date": "string", "source": "string", "file_id": "string" }
]
}
}
2. Write the Agent Prompt
Input JSON: suggested_file_name, type_of_file, description, main_person, other_persons, full_content, file_id.
Birthday example:
You extract birthday-related information from document metadata. Only use information explicitly present in the input; do not infer or guess.
Input is a JSON object with: suggested_file_name, type_of_file, description, main_person, other_persons, full_content (key-value from document).
Return a JSON object with:
- "birthdays": list of { "person_name": string, "date": string (YYYY-MM-DD or partial like "15 March"), "source": string, "file_id": string (pass through from input) }
If no birthday/date of birth is explicitly present, return { "birthdays": [] }. Do not fabricate dates.
3. Configure the Widget
| Field | Description |
|---|---|
| type | list_by_date, table, or card |
| list_key | Key in extracted JSON (e.g. birthdays) |
| sort_field | Field to sort by (e.g. date) |
| display_fields | Fields to show |
| title | Widget title |
| empty_message | Message when no data |
4. Publish via Admin
Use the VaultSafe Admin app (local only). Create or edit the app, set status (enable_for_all or enabled_by_user), and save.
Widget Types
| type | Use case |
|---|---|
| list_by_date | Sorted list, ideal for dates |
| table | Tabular view |
| card | Card layout |
App Status
- enable_for_all: Auto-enabled for all users. Backfill runs on publish.
- enabled_by_user: Marketplace only. Users enable explicitly.
Users can disable any app at any time.
User Data
- user_app.data: List of
{ file_id, extracted, updated_at }. - Users can add or edit items in the Apps UI via simple forms (e.g. birthdays, reminders)—no JSON or technical setup required.
- Updates sync to chat context for AI-assisted Q&A.
Full Example
See How to Build Apps for VaultSafe for a complete Birthdays app example.