PlanetLedger: AI-Powered Dashboard Transforms Bank Statements into Environmental Intelligence

A novel AI-powered sustainability finance dashboard, named PlanetLedger, has emerged from a recent developer challenge, aiming to revolutionize how individuals understand the environmental impact of their spending. This innovative tool processes bank statements, converting raw financial data into actionable environmental insights, and was showcased as part of the Weekend Challenge: Earth Day Edition.

The core functionality of PlanetLedger lies in its ability to ingest bank statements, provided in either CSV or PDF format. Upon upload, an advanced agent pipeline automatically analyzes the transactions. The primary objective is to illuminate the often-invisible environmental costs associated with everyday consumer choices, presenting this information in a readily understandable and actionable format, thereby eliminating the need for manual data compilation and analysis in spreadsheets.

The Genesis of PlanetLedger

PlanetLedger was developed as a prototype for a hackathon, emphasizing an "agent-first" approach to sustainability finance. The project’s architecture is designed for efficiency and scalability, with a clear flow: user interaction initiates a process involving authentication, data processing by the PlanetLedger agent, interaction with various APIs, generation of insights, and finally, presentation to the user interface.

The platform utilizes a sophisticated stack of technologies to achieve its goals. The framework of choice is Next.js 15.5 with its App Router and TypeScript, providing a robust foundation for building modern web applications. Authentication is handled by Auth0 v4, integrated seamlessly through middleware, minimizing the need for custom route handlers. This approach ensures secure and efficient user management.

At the heart of PlanetLedger’s analytical capabilities are AI and Large Language Models (LLMs). The system primarily leverages OpenAI’s gpt-4o-mini for its natural language processing tasks, with Google Gemini’s gemini-1.5-flash serving as a fallback. This dual LLM strategy ensures resilience and optimal performance. Complementing the AI, a custom categorization and scoring engine operates as a rules-based system, providing deterministic, explainable, and cost-free impact assessments. A Retrieval Augmented Generation (RAG) layer is employed to contextualize prompts with real spending data, enhancing the accuracy and relevance of the generated insights.

Data ingestion is facilitated by pdf-parse v2 for PDF documents, augmented with a specific regular expression extractor for Australian bank statements. For CSV files, papaparse is utilized, configured to handle the standard Australian format: Date / Transaction / Debit / Credit / Balance. The entire process is orchestrated by OpenClaw, a custom-built event-driven workflow runner, ensuring a smooth and responsive user experience. Styling is achieved through Tailwind CSS v3 and the Space Grotesk font, contributing to a clean and modern user interface. The platform is deployed on Vercel for optimal performance and scalability.

The Agent Pipeline: A Step-by-Step Analysis

The PlanetLedger agent pipeline operates in five distinct layers, executed sequentially with every user upload:

1. Parse: This initial stage handles the extraction of raw transaction data. For PDF statements, a regex-based approach first converts the text into a format consistent with CSV exports, standardizing dates (e.g., "03 Dec 2022"), amounts, and credit/debit indicators before parsing. The output is a typed Transaction[] array.

2. Categorise: The resolveCategory() function maps merchant names to one of seven predefined sustainability categories. This is achieved through a combination of regex and keyword matching against a database of known Australian vendors. Transactions that do not meet these criteria are passed to an LLM for reclassification, employing a low-temperature setting (0) and a maximum of 10 tokens to ensure speed and cost-effectiveness.

3. Score: The calculateImpactScore() function implements the core scoring engine. This system assigns points based on spending patterns within various categories. For instance, categories like "Travel," "Food & Drink," "Shopping," and "Utilities" are assigned baseline scores. Further refinement occurs based on specific transaction details, such as the type of travel (flights versus public transport) or the nature of shopping (sustainable brands versus fast fashion). The system also incorporates user-defined preferences, such as "no car ownership" or "low income mode," to personalize the scoring. Behavioral patterns, such as frequent fast-fashion purchases or excessive energy consumption, can further adjust the score.

4. Build RAG Context: Before generating any insights or chat responses, the buildRagContext() function curates a contextual summary of the user’s financial behavior. This includes the last seven days of transactions, the top two spending categories by volume, the top three merchants, and any identified behavioral patterns. This rich context is embedded into every prompt, ensuring that the AI’s responses are directly relevant to the user’s specific financial data.

5. Generate Insights: The insight pipeline produces structured outputs of type WARNING, POSITIVE, or NEUTRAL, along with accompanying messages. These insights are cached for three minutes and stored for future reference. The system is designed to identify and flag specific patterns, such as "3+ food delivery orders in a week" or "fast fashion spend exceeding $50," triggering tailored recommendations and alerts. Agent memory is maintained per user, keyed by their Auth0 sub identifier, allowing the system to learn and adapt to individual habits over time, becoming more accurate with each subsequent analysis.

Auth0 Integration: Securing the Agent

Auth0 plays a crucial role in securing PlanetLedger, with v4 integrated via Next.js middleware. This approach eliminates the need for dedicated authentication route files, streamlining the setup process. A single line of code in lib/auth0.ts initializes the Auth0 client, while middleware.ts handles the routing and authentication checks.

Crucially, every API route is protected by an internal agent scope check. The authorizeAgentScope function verifies that the user possesses the necessary permissions, such as read:transactions, write:insights, and update:score, before proceeding. These scopes are implemented as custom Auth0 claims, distinct from standard OIDC scopes, ensuring a clear separation of agent permissions from general OAuth functionalities. User preferences, like noCarOwnership and lowIncomeMode, along with the agent’s memory summary, are also stored as Auth0 custom claims, ensuring persistence across user sessions. The public-facing /demo page and the /api/upload/preview endpoint are intentionally excluded from the middleware matcher, allowing anonymous users to explore the application’s capabilities without requiring an account.

OpenClaw: The Event Bus for Automation

OpenClaw, a custom-built, lightweight in-process event system, facilitates automation without the need for external queue services. Three primary workflows are registered upon application startup:

• autoInsightOnUpload: This workflow triggers automatically with every CSV or PDF upload, executing the complete agent pipeline and caching the generated insights.
• highImpactAlert: This workflow is initiated when a user’s impact score drops below a threshold of 40 out of 100, logging a structured alert detailing the primary contributing categories.
• weeklyReport: This workflow can be triggered manually or on a schedule, generating a comprehensive digest of the user’s overall score, insights, and detailed spend breakdown.

Following a successful upload, the API handler dispatches a transactions_uploaded event to OpenClaw. This allows the route handler to return the parsed data to the user immediately, while the background processing of the agent pipeline continues asynchronously.

The /demo Page: Instant Environmental Insights

A notable feature of PlanetLedger is its /demo page, which offers a fully functional experience without requiring any authentication or network calls. This is achieved by utilizing a Next.js server component that imports sample CSV data as a TypeScript string constant. The parseTransactionsCsv() and calculateImpactScore() functions are then executed directly at build time. This results in a statically generated page that loads instantly, bypassing the need for middleware or database interactions. Premium features, such as AI-driven chat, a "What-If Simulator," and a "Memory Timeline," are presented as blurred, locked panels, providing visitors with a clear preview of the advanced functionalities available upon signing up.

Earth Day Design Choices and Engineering Decisions

In alignment with its Earth Day theme, PlanetLedger incorporates several thoughtful design choices. The core of its impact scoring relies on deterministic rules for transaction categorization rather than solely on LLMs. This approach ensures speed, cost-efficiency, and transparency, as each categorization decision can be traced back to a specific rule. LLMs are reserved for the "Other" fallback category, which accounts for approximately 10-15% of transactions, thus keeping operational costs minimal and enabling the rules engine to function even on the static demo page.

For user data persistence, an in-memory store (Map<userId, UserMemory>) was chosen for the weekend build, minimizing infrastructure requirements for development. The entire storage layer is abstracted behind a lib/store.ts interface, making it straightforward to transition to more robust solutions like Redis or PostgreSQL with minimal architectural changes.

The choice of Australian sample data was driven by the desire to thoroughly validate the vendor categorization rules within a specific market. While the parser is not inherently restricted to Australia and can process any CSV adhering to the Date / Transaction / Debit / Credit / Balance schema, the vendor-specific rules are currently tailored to Australian businesses. The intention is to build comprehensive coverage for one region before expanding, prioritizing depth over breadth.

Future Development Roadmap

While PlanetLedger represents a significant achievement for a weekend project, its developer has outlined an ambitious roadmap for future enhancements:

• Real LLM Integration for Chat and Insights: The current chat functionality relies on keyword matching and templated responses. The next step involves connecting the existing RAG context builder and prompt grounding mechanisms to advanced LLMs like GPT-4o or Gemini for truly conversational and insightful interactions.
• Persistent Database Implementation: The in-memory store is the primary bottleneck for production readiness. The plan is to migrate to PostgreSQL via Prisma to store transactions, scores, chat history, and memory timelines persistently, ensuring data survival across server restarts.
• International Smart Parsing: Enhancing the parsing capabilities to automatically detect and handle bank statement formats from various countries, including the US (Plaid/OFX), UK (Monzo/Starling CSV), EU (SEPA), and Australia, is a key objective. Future iterations may employ LLM-based "fuzzy CSV parsing" for broader format compatibility.
• Integration of Real CO2e Data: The current impact scores are proxy-based, relying on category and spend volume. The roadmap includes integrating with actual emissions APIs, such as Climatiq or Patch, to provide precise CO2e (carbon dioxide equivalent) grams per transaction category, thereby offering a scientifically measurable impact score.
• Email and Push Notifications: The highImpactAlert workflow in OpenClaw currently logs alerts to the console. The next phase involves integrating with services like Resend or push notification platforms to ensure these alerts reach users effectively.
• Mobile-Friendly Upload: To reduce user friction, a mobile-optimized upload flow is planned, potentially incorporating the ability to forward bank statement emails directly to PlanetLedger via a Cloudflare Email Worker or a similar solution.
• Expanded AI Agent Capabilities: Further development of AI agent functionalities is anticipated, including features like personalized financial advice, automated expense optimization suggestions, and proactive sustainability recommendations based on user spending habits.

PlanetLedger’s innovative approach to sustainability finance underscores the potential of AI to empower individuals with critical environmental data, transforming everyday financial decisions into opportunities for positive planetary impact.