How to Build Apps for VaultSafe

VaultSafe’s app ecosystem lets you build applications that run on document metadata—extracting birthdays, invoices, deadlines, or any structured data—and present it through configurable widgets. No code in the repo. All app definitions live in the cloud. Here’s how it works and how to create your first app.

The Pipeline

1. User uploads a file → VaultSafe’s AI analyzes it (document type, description, entities, key-value content).
2. Your app’s agent prompt runs on that metadata → extracts structured data (e.g. birthdays, due dates).
3. Data is stored per user, per app.
4. A widget renders the data (list, table, or card view).

Critical: Apps never see raw files. They only receive pre-extracted metadata. This keeps the system secure and fast.

Three Pieces of an App

1. Schema

Define what your app extracts. Example (Birthdays):

{
  "extraction": {
    "birthdays": [
      { "person_name": "string", "date": "string", "source": "string", "file_id": "string" }
    ]
  }
}

2. Agent Prompt

Instructions for the LLM. The input is 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 }

If no birthday is explicitly present, return { “birthdays”: [] }. Do not fabricate dates.

3. Widget Config

How to display the data:

App Status: Enable for All vs. Marketplace

When you publish an app, you choose:

• Enable for all — Automatically enabled for every user. Good for core features (e.g. Birthdays).
• Enabled by user — App appears in the marketplace. Users browse and enable it themselves.

Users can disable any app at any time.

Generic Widgets

More widget types (tree, timeline, etc.) can be added over time.

Publishing

1. Use the VaultSafe Admin app (local only, never deployed).
2. Create a new app with app_id, name, developer, agent_prompt, schema, widget.
3. Set status: enable_for_all or enabled_by_user.
4. Save. If enable_for_all, a backfill runs to add the app for all users.

User Data & RAG

• Extracted data is stored in user_app (user_id + app_id + data).
• Users can update or delete items in the Apps UI.
• App data is also embedded and stored in pgvector for LLM chat context. On update/delete, those chunks are kept in sync.

Full Example: Birthdays App

{
  "app_id": "birthday",
  "name": "Birthdays",
  "developer": "vaultsafe",
  "cost": 0,
  "price_display": "Free",
  "status": "enable_for_all",
  "agent_prompt": "...",
  "schema": { "extraction": { "birthdays": [...] } },
  "widget": {
    "type": "list_by_date",
    "list_key": "birthdays",
    "sort_field": "date",
    "display_fields": ["person_name", "date", "source"],
    "title": "Birthdays",
    "empty_message": "No birthdays extracted yet."
  }
}

Next Steps

• Read the App Developer Guide for full specs.
• Check Marketplace apps for the ecosystem overview.
• Contact support@vaultsafe.ai for the developer program.