Build custom financial applications on top of Datarails FinanceOS using Lovable's AI-powered app builder - no coding required.

Overview

Lovable is an AI-powered web application builder that generates full-stack React apps from natural language prompts. Combined with the Datarails FinanceOS SDK, finance teams can rapidly build custom dashboards, reports, and analytical tools that pull live financial data directly from their Datarails environment.

What You Can Build

• Budget vs Actuals dashboards
• P&L statements and executive summaries
• Variance analysis boards
• Revenue trend and growth dashboards
• Expense trackers and anomaly detectors
• Scenario comparison tools
• Multi-currency exposure views
• Data quality monitors
• Any custom financial application your team needs

Prerequisites

Before building your first Lovable app with Datarails, ensure the following:

• Datarails account - An active Datarails FinanceOS environment with user credentials that have appropriate data access permissions.
• Lovable account - A Lovable account at lovable.dev. No coding experience required, but familiarity with prompt-based iteration helps.
• Data readiness - Your GL data should be mapped and classified in Datarails (accounts, departments, scenarios, etc.). The SDK can discover available tables and dimensions dynamically.
• The FinanceOS connection is enabled in your Datarails environment. If it does not, reach out to your CSM.

Step 1: Start a New Lovable Project

1. Go to lovable.dev and create a new project.
2. Begin every Lovable app with this prompt:

Please download dr-financeos-sdk from datarails public npm repo
https://datarails.jfrog.io/artifactory/api/npm/dr-npm-client-virtual/
and build an app from it

3. Lovable will install the SDK from the Datarails public npm registry and scaffold an initial app structure with authentication wired up.

Important: This exact prompt must be used as the starting point for every new Lovable project that integrates with Datarails. It ensures the SDK is pulled from the correct registry and the authentication flow is set up properly.

Step 2: Describe Your Application

After the SDK is installed, follow up with a prompt describing the app you want to build. For example:

Build a Budget vs Actuals Dashboard that:
- Discovers available tables and scenarios using the SDK
- Lets users filter by Department and Period
- Shows summary cards for Total Budget, Total Actuals, and Variance
- Includes a grouped bar chart comparing Budget vs Actuals by account category
- Uses client.tables.aggregate() for data fetching

Be specific about the layout, chart types, and data-fetching methods. See the Best Practices section below for prompting tips.

Step 3: Authenticate and Test

1. Once Lovable generates the app, open the preview.
2. Click "Connect to Datarails" to authenticate.
3. Important: Authentication must happen in a pop-up window (see Troubleshooting section if it opens in an iframe instead). If it doesn't, open the app in another tab: 
4. After authentication, the app will fetch live data from your Datarails environment.

Security & Data Access

Datarails manages all end-user credentials and data permissions. Users interacting with Lovable-built apps based on the Datarails integration will only see data they are permitted to see in Datarails.

• The SDK authenticates each user individually via OAuth.
• Row-level and role-based access controls defined in Datarails are enforced for every API call.
• App builders do not need to implement their own authorization layer - Datarails handles this transparently.
• You do not need to store or manage user passwords.
• Each user authenticates with their own Datarails credentials.
• The same Lovable app can serve multiple users with different permission levels, and each will see only their authorized data.
• Tokens are stored in the user's browser (localStorage) and auto-refreshed via the SDK.

Third-Party Responsibility (Lovable) Lovable is an independent third-party service not operated or controlled by Datarails. While Datarails enforces authentication and access controls for all data served through the FinanceOS SDK, apps you build are hosted, generated, and run on Lovable's platform. Your use of Lovable — including how application code, browser-stored tokens, and any data rendered in the app are handled — is governed by Lovable's own terms of service and privacy policy. You are responsible for reviewing those terms and for ensuring your use of Lovable complies with your organization's data-handling and compliance obligations. Review Lovable's privacy policy here: https://lovable.dev/privacy.

SDK Authentication Flow

The FinanceOS SDK uses an OAuth 2.0 PKCE flow:

1. Check for saved tokens - On app load, check localStorage for existing tokens (access, refresh, envUrl).
2. Show login button - If no tokens exist, display a "Connect to Datarails" button.
3. Initiate auth -  On click, call FinanceOSAuth.createAuthRequest() with your callback URL and client ID.
4. Handle callback - After the user authenticates, extract the token from query params and call FinanceOSAuth.handleCallback().
5. Create client - Instantiate new FinanceOSClient(tokens) with the returned token pair.
6. Auto-refresh - Before every API call, call client.ensureValidToken() to handle token refresh automatically.

SDK Quick Reference

Key Methods

Aggregation Types

SUM, COUNT, COUNT_UNIQUE, AVG, MIN, MAX, UNIQUE_VALUES

Filter Pattern

{
  "name": "ColumnName",
  "values": ["Value1", "Value2"],
  "isExcluded": false
}

• isExcluded: false - include only these values (whitelist)
• isExcluded: true - exclude these values (blacklist)

Common Financial Filters

Best Practices

Prompting Lovable Effectively

1. Always start with the SDK install prompt - Every new project must begin with the standard prompt to download dr-financeos-sdk from the Datarails npm registry.
2. Use data discovery - Instruct Lovable to use client.tables.listTables() and client.tables.distinctValues() to discover available data dynamically rather than hardcoding table names or filter values.
3. Be specific about layout - Describe the dashboard structure (cards, charts, tables) and their arrangement.
4. Specify chart types - Name the chart library (Recharts is well-supported) and chart types (bar, line, area, donut, etc.).
5. Request loading states - Always ask for skeleton loaders or spinners while data loads.
6. Ask for responsive design - Lovable apps should work on desktop and mobile.
7. Iterate incrementally - Start with a basic version and add features through follow-up prompts.

Data Fetching Patterns

1. Use aggregate() for summaries - Don't fetch raw data when you only need totals; use aggregation with dimensions and metrics.
2. Fetch in parallel - When comparing scenarios (e.g., Actuals vs Budget), use Promise.all() to fetch both simultaneously.
3. Always call ensureValidToken() - Before every API call, ensure the token is fresh.
4. Cache dimension values - Store results from distinctValues() to populate dropdowns without repeated API calls.
5. Join client-side - When comparing datasets (Budget vs Actuals), fetch separately and join by matching dimensions (account + period).

App Design Tips

1. Follow financial reporting conventions - Use parentheses for negatives, right-align numbers, format with commas.
2. Color-code variances - Green for favorable, red for unfavorable.
3. Include export options - CSV export for tables, PNG for charts, print-friendly CSS for reports.
4. Add context - Show "Last refreshed" timestamps, data period ranges, and filter indicators.
5. Use collapsible hierarchies - Financial data is hierarchical (L1 > L2 > L3); let users drill down.

Troubleshooting

Authentication Opens in Iframe Instead of Pop-up

Problem: Lovable sometimes prompts you to log in within an iframe embedded in the app preview. The authentication flow does not work inside an iframe.

Solution: Authentication must happen in a pop-up window, not an iframe. If you encounter this:

1. When prompted to authenticate, ensure the auth flow opens in a new browser window/pop-up rather than inline.
2. If Lovable is rendering the auth screen inside the app preview iframe, instruct Lovable to change the auth behavior with this prompt:

The Datarails authentication flow must open in a pop-up window,
not inside an iframe. Please update the auth logic to use
window.open() for the authentication URL instead of redirecting
within the iframe.

3. After authenticating in the pop-up, the pop-up will redirect back with tokens, and the main app window should pick them up.
4. If the issue persists, try opening the Lovable preview in a separate browser tab (not the embedded preview) and authenticate from there.

SDK Installation Fails

Problem: Lovable cannot find or install dr-financeos-sdk.

Solution:

• Ensure you included the full registry URL in your prompt: https://datarails.jfrog.io/artifactory/api/npm/dr-npm-client-virtual/
• Ask Lovable to configure the npm registry before installing:

Configure npm to use the Datarails registry:
npm config set @datarails:registry https://datarails.jfrog.io/artifactory/api/npm/dr-npm-client-virtual/
Then install the SDK: npm install dr-financeos-sdk

API Calls Return Empty Data

Problem: The app loads and authenticates, but charts and tables are empty.

Solution:

1. Check table discovery - Ensure client.tables.listTables() returns tables. If not, the user may lack permissions.
2. Check filter values - Use client.tables.distinctValues() to verify the dimension values you're filtering on actually exist (e.g., "Actuals" vs "ACTUALS" - values are case-sensitive).
3. Check date ranges - Ensure the reporting date filter matches periods that have data.
4. Check scenario names - Scenario names vary by environment; discover them dynamically rather than hardcoding.

Token Refresh Errors

Problem: The app works initially but fails after a period of inactivity.

Solution:

• Ensure client.ensureValidToken() is called before every API request.
• After calling ensureValidToken(), update localStorage with client.tokens in case the token was refreshed.
• If the refresh token has expired, the user will need to re-authenticate - show a "Reconnect" button.

Charts Not Rendering / Compilation Errors

Problem: Lovable generates code that doesn't compile or charts don't render.

Solution:

• Ask Lovable to fix the specific error: paste the error message into the Lovable chat.
• Ensure Recharts is included as a dependency (it's the most reliable charting library in Lovable).
• For complex charts, simplify first and add features incrementally.
• If a specific chart type fails, ask Lovable to use an alternative (e.g., bar chart instead of waterfall).

CORS Errors

Problem: API calls fail with CORS (Cross-Origin Resource Sharing) errors in the browser console.

Solution:

• This typically occurs when the callback URL doesn't match the app's origin.
• Ensure the callbackUrl in FinanceOSAuth.createAuthRequest() matches window.location.origin + "/callback".
• If testing locally vs in Lovable's preview, the origins will differ -  use window.location.origin dynamically.

App Works in Preview but Not After Deploy

Problem: The app functions in Lovable's preview mode but breaks when deployed.

Solution:

• Verify the deployed URL's /callback route is properly handled (React Router must catch it).
• Ensure localStorage is accessible on the deployed domain.
• Check that the deployed domain is allowed in Datarails OAuth configuration.
• The callbackUrl must match the actual deployed URL, not the Lovable preview URL.

Example App Prompts

Datarails maintains a library of tested Lovable prompts for common financial applications:

Contact your Datarails representative for access to these prompt templates.

Frequently Asked Questions

Do I need to be a developer to build Lovable apps with Datarails?
No. Lovable generates the code from natural language prompts. However, understanding basic concepts like filters, aggregations, and dashboard layouts will help you write better prompts.

Can multiple users use the same Lovable app?
Yes. Each user authenticates with their own Datarails credentials and sees only the data they are permitted to access. Datarails manages all authorization.

Is my financial data safe?
Datarails enforces all access controls, and data flows to the user's browser via the SDK using each user's own authenticated permissions. Datarails does not transmit your financial data to Lovable's servers. However, Lovable is a third-party platform that hosts and runs your app; how data is handled within that environment is subject to Lovable's own terms and privacy policy. Please review Lovable's privacy policy (https://lovable.dev/privacy) before using it with financial data.

Can I customize the app after Lovable generates it?
Yes. You can iterate by chatting with Lovable ("add a department filter", "change the chart colors", "add CSV export"). You can also export the source code for further customization.

What if my Datarails environment has custom table names or dimensions?
Use data discovery methods (listTables(), distinctValues()) in your prompts so the app adapts to your environment dynamically rather than relying on hardcoded values.

Why do I get an "Authentication denied" message when I try to authenticate?

This typically happens because the FinanceOS AI platform connection is not yet enabled for your organization in Datarails. This setting must be activated before Lovable apps can authenticate against your environment.
To resolve this: Reach out to your Datarails Customer Success Manager (CSM) and ask them to enable the "Connect Datarails to AI platforms" option for your account. Once enabled, retry the authentication flow, and it should succeed.