Developed by Rui Ribeiro
The demo runs on an Azure virtual machine and may be temporarily unavailable when the VM is switched off.
DenariusAI is a personal and family finance management platform built around double-entry accounting. It combines daily financial management with budgeting, bank reconciliation, savings, investments, insurance, analytics and administrative organisation in one secure and consistent workspace.
AI features assist with transaction entry, classification, financial questions, correspondence analysis and Markdown report generation. The AI layer is provider-neutral and currently supports Mistral AI, GroqCloud and NVIDIA NIM for cloud inference, plus Ollama for local or privately hosted inference. Suggestions are always reviewed by the user before relevant data is saved.
- Double-entry financial management with accounts, groups, categories and transactions
- Monthly budgeting and transaction allocation
- AI-assisted bank reconciliation and transaction classification
- Configurable, provider-neutral AI integration with Mistral AI, GroqCloud, NVIDIA NIM and Ollama
- Dashboards, period comparisons and financial analytics
- Portuguese Savings Certificates portfolio, official Série F rate history and indicative next-month ARIMA forecast
- Configurable IGCP source URLs for Savings Certificate rate collection
- Stock portfolio and watchlist with market price history, performance tracking and optional ARIMA forecasts
- Automatic stock market history collection through a configurable market-data provider
- Insurance portfolio with policy details, premium records, renewal dates and status tracking
- Document, correspondence and warranty management
- Reminders and alerts for relevant dates and expirations
- AI-assisted correspondence analysis and metadata extraction
- AI-powered financial assistant and intelligent reports
- Authentication, user roles, administrative auditing and configurable application settings
- Optional read-only MCP financial tools
DenariusAI organises day-to-day finances around accounts, financial groups, categories and double-entry journal entries. Transactions can represent income, expenses and transfers while keeping the accounting structure balanced and providing a consistent basis for balances, statements, reconciliation and reporting.
The same financial model is shared by the application's operational and analytical areas, so information entered once can be reused across budgets, dashboards and financial analysis without delegating deterministic calculations to the AI layer.
Monthly budgets provide a planning layer over registered financial activity. Amounts can be allocated across the configured financial structure and compared with actual transactions, making it possible to follow planned versus realised values throughout the month.
Budget information remains connected to the underlying financial records, allowing the user to review execution in the same workspace used for transaction management and analysis.
The reconciliation workflow helps match bank activity with DenariusAI financial records and supports transaction classification. AI assistance can propose classifications and interpretations where configured, while the user remains responsible for reviewing the proposed result before financial data is changed.
This combines automation with explicit user control and keeps reconciliation tied to the application's double-entry accounting model.
Dashboards and analytics turn registered financial data into period-based views of income, expenses, balances and financial evolution. Comparisons across periods help identify changes in spending and other relevant trends without requiring a separate reporting system.
Analytical results are calculated from application data, while AI can be used separately to explain or contextualise information when that assistance is enabled.
The Savings Certificates portfolio tracks Portuguese savings-certificate subscriptions as part of the household's broader financial position. Registered holdings can be followed over time with their associated values and projections, keeping this form of savings visible alongside cash accounts and other investments.
A dedicated rate-history screen can collect the official gross Série F rate for new subscriptions from monthly IGCP publications and display 3, 6 or 12 months of observations. The chart supports point inspection on hover, while the imported reference history remains separate from each registered certificate's own rate and never revalues existing holdings automatically.
When enough monthly observations are available, DenariusAI calculates an indicative ARIMA(0,1,0) forecast with drift for the next calendar month, including a 95% confidence interval and rolling validation error. This forecast is explicitly separate from any official IGCP announcement and is never used automatically to change financial records.
The IGCP source page and monthly publication URL template are administrator-editable application settings. Existing installations retain safe defaults; changing these settings affects the next history refresh without requiring an application restart.
The stock portfolio brings listed investments into the same personal-finance workspace. Positions can be registered with ticker, exchange, trading currency, quantity and average purchase price, while the watchlist can also track instruments that are not currently held.
Historical market prices can be collected from the configured provider and are used to show price evolution, period change, minimum and maximum prices, and current unrealised gain or loss. When enabled and enough observations are available, DenariusAI can also calculate deterministic ARIMA-based 30, 60 and 90-day price forecasts with 95% confidence intervals. Forecasts are indicative only and never change financial records automatically.
The insurance portfolio centralises personal and family policies in DenariusAI. Policies can be registered by type, insurer, policy number and insured object, together with start and renewal dates, payment frequency, status and notes. Premium amounts are maintained as separate records associated with each policy.
The portfolio dashboard provides an overview of active policies and registered insurance costs for the current year, together with outstanding premium information and upcoming renewal dates. This keeps recurring insurance commitments visible alongside the rest of the user's financial information.
DenariusAI also provides administrative areas for information that belongs around personal and family finances but is not itself an accounting transaction. Documents, correspondence and warranties can be maintained in the application so relevant records and dates remain accessible from the same workspace.
Correspondence can use configured AI assistance for analysis and metadata extraction, helping interpret incoming information while leaving stored records and their final classification under user control.
Relevant dates and expirations can be surfaced through reminders and alerts. This provides a common way to keep time-sensitive financial and administrative commitments visible rather than relying only on the individual area where each record was created.
The reminder layer complements areas such as documents and warranties by drawing attention to dates that may require action.
The optional financial assistant provides a natural-language interface for questions about the user's DenariusAI data. AI is also used in selected workflows for interpretation, classification assistance and Markdown report generation.
The AI provider is configurable in the application settings. Mistral AI remains the default cloud provider, GroqCloud and NVIDIA NIM are also available for cloud inference, and Ollama can run a compatible model through a local or privately hosted Ollama server. Business workflows consume the provider-neutral ILLMService boundary rather than depending directly on a specific vendor. With Ollama running inside the installation's trusted infrastructure, prompts and financial context sent to the model do not need to be processed by a third-party cloud AI provider.
The AI layer is deliberately advisory: deterministic financial calculations remain application responsibilities, and suggestions that would affect financial records remain subject to user review.
DenariusAI includes authentication, user and role management, administrative auditing and configurable application settings. These capabilities support controlled access to personal-finance information and provide administrators with the tools required to manage an installation without mixing administration with normal financial workflows.
Optional Google authentication can be enabled for existing users while local authentication remains available. Google sign-in does not automatically provision new DenariusAI users.
An optional Model Context Protocol (MCP) surface exposes read-only financial tools for compatible external AI clients and integrations. This allows selected DenariusAI information to be queried through a structured interface without giving the MCP layer permission to modify financial records.
The read-only design preserves the application's principle that financial changes remain controlled by DenariusAI workflows and the user.
| Technology | Role |
|---|---|
| .NET 9 / ASP.NET Core MVC | Web application and business workflows |
| Entity Framework Core | Persistence and database migrations |
| SQL Server 2022 | Financial and identity data |
| Mistral AI | Optional cloud AI provider for natural-language assistance and reports |
| GroqCloud | Optional cloud AI provider for natural-language assistance and reports |
| NVIDIA NIM | Optional OpenAI-compatible cloud AI provider for NVIDIA-hosted models |
| Ollama | Optional local or privately hosted AI inference |
| Docker Compose | Reproducible local deployment |
| xUnit | Unit, integration and MCP tests |
Requirements: Docker Engine or Docker Desktop with Docker Compose.
git clone https://github.com/ruialexrib/denarius-ai.git
cd denarius-ai
Copy-Item .env.example .envSet secure local passwords in .env. If you intend to use Mistral AI, add MISTRAL_API_KEY; if you intend to use GroqCloud, add GROQ_API_KEY; if you intend to use NVIDIA NIM, add NVIDIA_NIM_API_KEY. Ollama does not require a cloud-provider API key. Then start the application:
docker compose up --build -d
docker compose psOpen http://localhost:8080.
docker compose logs -f denarius-ai-web
docker compose downNever commit .env, credentials or real financial data.
DenariusAI currently includes four AI providers. Mistral AI is the installation default and uses remote cloud inference with MISTRAL_API_KEY. GroqCloud is an alternative cloud provider and uses GROQ_API_KEY. NVIDIA NIM uses NVIDIA's OpenAI-compatible hosted inference API and the deployment-only NVIDIA_NIM_API_KEY. Ollama can run compatible models locally or through a privately hosted Ollama server and does not require a cloud-provider API key.
The provider is selected in the application's administrative settings through AI.Provider. The supported provider identifiers are Mistral, GroqCloud, NvidiaNim and Ollama. Provider-specific models, endpoints and other non-secret options are also configured through the application settings where supported. The NVIDIA NIM hosted defaults are NvidiaNim.BaseUrl = https://integrate.api.nvidia.com/v1/ and NvidiaNim.Model = meta/llama-3.1-8b-instruct; both can be changed by an administrator without storing the API key in application settings.
For local AI, install Ollama, download a suitable model and make the Ollama server reachable from the DenariusAI web application. Select Ollama as the provider and configure its model and endpoint. The built-in Ollama defaults are:
Ollama.Model = llama3.2
Ollama.BaseUrl = http://localhost:11434
Set AI.Provider to Ollama in the administrative settings to use these Ollama settings. Mistral remains the application's default provider until that selection is changed. These are application settings rather than required .env variables and can be changed by an administrator. Ollama.BaseUrl may point to a local or remote HTTP/HTTPS Ollama endpoint. When DenariusAI itself runs in Docker, remember that localhost inside the web container refers to that container; configure an address that the container can use to reach the Ollama service.
Application AI workflows remain independent of the selected vendor. They consume ILLMService; concrete providers implement ILLMProvider and are registered through the ASP.NET Core dependency-injection container. ConfigurableLLMService resolves the adapter named by AI.Provider. Adding another provider normally requires a new adapter, dependency-injection registration and the corresponding provider configuration/settings support, without changes to financial workflows that already consume ILLMService.
Regardless of provider, AI output remains advisory: DenariusAI performs deterministic financial calculations itself and the user confirms changes to financial records.
AI.Provider selects a registered provider explicitly; unknown values fail rather than silently falling back to Mistral. Shared generation settings use AI.MaxTokens and AI.Temperature, with legacy Mistral keys retained only as compatibility fallbacks. Adding another provider normally requires only its adapter, dependency-injection registration and configuration support.
Assistant and movement-suggestion requests are bounded by AI.MaxInputBytes (default 12,000; configurable from 4,000 to 64,000 bytes) and an output cap of 1,024 tokens. Financial context uses deterministic totals, capped samples and limited history; movement IDs are validated against the catalog sent to the model. Oversized requests may retry once with reduced context, and financial records remain unchanged until user confirmation.
Stock price history, portfolio updates and watchlist market data use the Alpha Vantage service. Create a free API key at Alpha Vantage and add it to your .env file:
MARKET_DATA_API_KEY=your_api_key
The API key is required only for stock market data features. Keep it private and never commit it to the repository.
Savings Certificate reference-rate history uses public IGCP pages and does not require an API key. Administrators can change the endpoints from Definições da aplicação → Taxas dos Certificados de Aforro.
The effective settings are stored in the application's existing settings store:
SavingsCertificates.IgcpSourceUrl = https://www.igcp.pt/pt/aforristas/produtos-de-aforro/certificados-de-aforro
SavingsCertificates.IgcpPublicationUrlTemplate = https://www.igcp.pt/pt/noticias/taxas-de-juro-dos-certificados-de-aforro-das-series-b-d-e-e-f-em-{month}-de-{year}
The publication template must be an HTTPS URL and retain both {month} and {year} placeholders. These URLs contain no credentials. A failed refresh preserves the previously stored history, and imported reference rates remain separate from rates saved on individual certificate holdings.
User provisioning remains exclusive to DenariusAI administrators. Google authentication never creates a local account: access is granted only when the Google email exactly matches an existing application user. The same user can continue to sign in with the local email and password.
Create OAuth 2.0 web credentials in Google Cloud and register this authorized redirect URI for a local installation:
http://localhost:8080/signin-google
For a public installation, register the equivalent HTTPS address for its domain. Configure the credentials in .env:
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
When either value is absent, the Google button is not displayed and local authentication continues to work normally.
Distributed under the MIT License. Copyright © 2026 Rui Ribeiro.