Custodia Wireframe App

1. What the Wireframe App Is

The Wireframe app is a real, working Flutter application that shows how to build a client app on the Custodia platform. It is a live reference implementation: every feature runs against the platform APIs.

The UI is intentionally clean and unstyled (black and white) so you can focus on flows and API usage, then apply your own branding and design system.

With the Wireframe app you get:

• A working showcase of the platform’s APIs and client patterns
• Self-contained, copyable feature implementations (auth, card viewing, activities, impersonation, and more)
• A reference you can learn from on Flutter or map to another tech stack

2. What the Repo Provides

When you receive access to the core repo, you get more than the wireframe:

• A working reference app: the Wireframe under .custodia/wireframe/, with self-contained feature modules you can study or copy
• An app shell to customize: your product work under lib/, which ships with placeholder screens
• Project structure and setup scripts for a Flutter-based app (including .custodia/scripts/setup.sh)
• API client patterns via the Dart SDK: the wireframe shows how to call the platform; the SDK is a separate dependency used by the reference app
• Ongoing wireframe updates: new reference features are pushed periodically; forked apps can sync upstream for content they leave untouched

Repo layout

Location	Contents
.custodia/wireframe/	The full Wireframe Flutter app: all current features, used as working examples
.custodia/scripts/	Setup and upstream-sync tooling for forks
lib/	Your app shell. Ships with placeholder screens; add features here (the root navigation shell has a fixed tab contract)
android/, ios/, config/	Native identity, branding, and runtime config you customize per product

3. Choose Your Path

There is no requirement to use the wireframe at all. Pick the approach that fits your team.

Path A: Build a fully custom app

Ignore (or delete) the Flutter UI and use your own stack. Use the wireframe as a living reference for how each API is meant to be used, and integrate the platform via the HTTP APIs (or the appropriate client SDK for your stack).

Best for: teams with an existing app or a strong preference for a non-Flutter stack.

Path B: Extend the Flutter app

Fork the repo and build your app under lib/, copying the wireframe’s structure or using a custom architecture. Copy any feature module from .custodia/wireframe/ and modify it freely.

Note: once you copy and modify wireframe code, that code is detached: it won’t receive wireframe updates. Code you leave untouched in the repo continues to benefit from periodic pushes.

Best for: teams starting fresh who want the fastest route to a working app.

Path C: Cherry-pick building blocks

Combine selected features into a new app (for example, an employee spending app with only auth, card viewing, and activities). Each feature folder is self-contained, so you take only what you need.

Best for: focused apps with a subset of platform functionality.

4. What the Wireframe Covers

The wireframe demonstrates the main product areas partners typically need. Each area is a self-contained module you can study or copy. Descriptions below are intentionally high level.

Area	What it shows
Authentication	Sign-in, session handling, and secure access to the platform
Onboarding	First-run setup and permissions a new user completes before using the app
Cards	View cards, card details, ordering, activation, and card-related actions
Card products	Browse available card products and product-specific configuration
Transactions (expenses)	Transaction history, filtering, and expense detail views
Activities	Spend activities: viewing, managing, and working with allocated spend
Activity creation	Creating new spend activities (general expense, business meeting, and related flows)
Budgets	Budget visibility and how spend ties back to budget lines
Out of pocket	Personal spend and converting eligible expenses to business spend
Expense clarification	Receipt capture, missing-info flows, and rematching expenses to activities
Notifications	In-app notification threads and action handling
Settings & profile	App preferences, language, and account-related settings
Impersonation	Support-style user impersonation for testing and admin workflows
Help & support	In-app help, knowledge base, and support entry points

Not every partner needs every area. Use the wireframe to see which flows matter for your product, then copy only those modules into your app.

5. Getting Started

1. Get repo access from your Custodia integration contact and fork the core repo for your product.
2. Open it in your IDE: Android Studio or any Flutter-compatible IDE. We recommend reading the repo in an AI-assisted editor like Cursor to get oriented quickly.
3. Run the one-shot setup script (.custodia/scripts/setup.sh) to install the pinned Flutter version and dependencies.
4. Explore the structure: run the wireframe reference app first to see working features, then look at the placeholder app shell under lib/.
5. Run the app: build to a simulator or connect a physical device and select it from the device dropdown.

Primary targets are Android and iOS. Desktop and web folders are scaffolded in the repo but are not the focus for Custodia client apps.

Not using Flutter?

• Other mobile stacks: the Flutter wireframe still shows how each API is used. Your team (or a coding agency) can map that to React Native or native code.
• HTTP-first teams: use the Partner Hub API guides for agentic payments and white label; treat the wireframe as optional reading for mobile UX and call patterns.

6. FAQ

Do we have to use the whole wireframe?
No. Cherry-pick features, extend the app, or ignore it completely.

If we copy wireframe code, do we get updates to it?
No. Copied and modified code is detached. Unmodified repo content continues to receive periodic wireframe updates.

How do branding and design work?
The wireframe focuses on functionality and API usage. You apply your own visual design and branding when you build your product app.

Back to Partner Hub