When AI gets immigration law wrong, the cost is not a bad essay

How I built a local AI legal assistant for German immigration law, what it took to get it right, and why “good enough” was never an option.

There is a moment most foreigners living in Germany will recognise. You are trying to understand a statutory condition for your visa or residence permit. You have the official government page open in one tab. You have a forum thread from 2021 open in another. You have asked a general-purpose AI assistant, which gave you a confident, well-structured answer citing a section of law that was amended two years ago.

None of these three sources agrees with the others.

I came from India, did my MBA in Germany, and stayed to build a career in Frankfurt. The immigration system I have navigated is genuinely complex. German residence law spans multiple statutes, each with distinct scopes and cross-referencing conditions. It is updated by legislation. And it is misrepresented constantly, both by outdated internet sources and by AI systems trained on data that predates the most recent reforms.

I built this project because I needed it. I also built it because the problem it addresses does not stop with my personal situation.

---

The obvious question

The first thing anyone asks when I describe this project is why I did not just upload the law to Claude or ChatGPT and ask my question.

It is a fair question. A frontier model with a large context window can ingest a legal document and answer questions about it reasonably well. For a one-off query, that is a perfectly rational approach.

But it is not the right architecture for anything that needs to be trusted, repeated, or used at scale. Here is why.

Frontier models hallucinate legal citations. Not occasionally. When legal text is complex, cross-referenced, and recently amended, a general-purpose model will sometimes generate section numbers that look plausible, cite provisions that have been replaced, or conflate two different legal regimes. The model is confident. The output looks correct. The error only surfaces when someone checks the actual statute.

A wrong answer in an immigration query is not a minor inconvenience. It can mean a rejected application, a missed condition, or a misunderstood right. A rejected application does not just cost time. For an employer, it means legal fees, delayed start dates, and direct financial liability. For the individual, it can mean months lost and a disrupted life plan. The stakes are simply not the same as getting a recipe slightly wrong.

Routing personal data to a cloud API is a choice with consequences. An immigration question carries nationality, employment status, family situation, and income details. These are sensitive personal data under GDPR. Sending them to a US-based cloud API in a casual query is a data governance decision that most people make without realising they are making it.

A tool you cannot explain is a tool you cannot trust. If the system gives you an answer, you need to be able to see exactly which section of law it drew from, read the German text yourself, and verify it. A general-purpose model gives you a response. This system shows you its work.

Those four constraints together defined the architecture before a single line of code was written.

---

The design brief

The requirements that came out of that thinking were straightforward.

The system had to run entirely on local hardware. No query, no document, and no personal detail should ever leave the machine. This is not a performance optimisation. It is a data architecture decision grounded in GDPR, professional liability, and the basic principle that a legal query deserves the same confidentiality as a legal consultation.

The system had to be grounded in current statute text rather than trained on historical summaries. The actual law was downloaded directly from the German government’s statutory publication source, indexed, and made retrievable at the section level. When the law changes, you rebuild the index. The system’s knowledge does not drift.

Every answer had to show the source. I did not want a footnote or a general reference to the relevant act. The exact German text of the section it drew from needed to be visible alongside the answer, so the user could read it themselves.

The scope also had to be honest. German immigration law covers three statutes: the general residence act for third-country nationals, the free movement act for EU citizens, and the employment ordinance for work permit approvals. These are the three laws in the index. Questions about citizenship, asylum, or social benefits are outside scope. The system explicitly states its limitations when asked, rather than inventing an answer from adjacent knowledge.

That last point matters more than it sounds. A system that knows its limits and communicates them clearly is much more trustworthy than one that attempts to answer everything.

---

Architecture decisions

The core architecture is a retrieval-augmented generation pipeline. The concept is straightforward. Instead of relying on a model’s training memory, you retrieve the relevant text from a controlled corpus first. You then generate a response grounded only in what was retrieved. The model is not guessing. It is reading.

Chunking at the section boundary. Legal text cannot be chunked the way prose is chunked. A statutory condition often spans multiple subsections within a single paragraph. Requirements for a given permit type might state the qualification condition in one subsection, the salary threshold in another, and the exceptions in a third. If a chunk boundary falls between them, any retrieval that returns only one subsection is retrieving half a legal condition. The chunking strategy here splits the corpus at section headers. This guarantees one complete statutory section per chunk. The integrity of the legal unit is non-negotiable.

Cross-lingual retrieval. The corpus is in German. A user asking in English needs to retrieve chunks using German statutory vocabulary. The solution is a two-step approach. The query is first expanded into the German legal terms, section numbers, and statutory vocabulary that correspond to the question. That expanded query is what gets embedded and matched against the corpus.

Two-stage retrieval. The first stage is vector similarity, which is fast but approximate. It retrieves candidates based on embedding proximity, not necessarily on actual legal relevance. The second stage is a cross-encoder reranker. It takes the query and each retrieved candidate together and scores the genuine relevance of the pair. The top five sections from that second stage are what get passed to the language model. This two-stage approach was the single biggest driver of answer quality improvement in the project. It also adds seconds to the response time. This is a trade-off made deliberately. In a legal context, a user will wait fifteen seconds for a correct, private answer. They will not wait at all for a fast, wrong one.

Model choice is infrastructure, not identity. The language model is not the product here. It is just a component. The system is designed to run any locally-served model. The corpus coverage and retrieval quality remain constant regardless of which model generates the final response. The true intelligence of the system lives in the retrieval pipeline, not in the model weights.

---

How it works

The RAG insight panel exists for one reason: transparency. It shows similarity scores and reranking scores side by side for every retrieved section. A user should be able to see exactly why a section was or was not included in the answer. That visibility is a core part of the trust contract.

---

The quality gate

Building a system is one thing. Knowing whether it works is another. Testing it requires stepping outside the builder’s perspective entirely.

I ran the system through a structured cross-evaluation using a set of questions a real user would ask. I checked these against the actual statute text to look for where the answers failed. This was not a test of latency or token throughput. It was a test of legal accuracy. Does the answer cite the right provision? Does it state the conditions correctly? Does it avoid inventing requirements that do not exist in the retrieved text?

The results were instructive. For straightforward queries, the system performed well. Eligibility conditions, the distinction between different legal regimes for EU versus non-EU nationals, and the routing between different statutes all came back with accurate citations and appropriate legal framing.

The failures were also clear. In some cases, the retrieval returned the right general area of law but the wrong section. In a small number of cases, the system cited a reference that did not correspond to what it actually retrieved. These were retrieval failures more than generation failures, but the output was wrong either way.

Those findings shaped the next round of architectural decisions. I implemented tighter reranking thresholds, added a second retrieval pass when confidence was low, and placed more explicit guardrails in the generation prompt around citation discipline.

The principle this established is worth naming clearly. Accuracy evaluation in a regulated domain cannot be done by the builder alone. The test questions need to come from someone who knows the domain well enough to catch a plausible but wrong answer. Technical benchmarks measure technical performance. They do not measure whether the answer is legally correct.

---

What comes next

Retrieval-augmented generation with vector similarity search is effective for straightforward queries. It is not sufficient for complex legal reasoning.

The limitation is structural. A flat vector index retrieves sections based on semantic proximity to the query. It does not model how sections relate to each other. One provision might establish a general condition that another provision qualifies. A right established in one statute may be constrained by a cross-reference to another. A correct answer to a complex question sometimes requires reasoning across multiple sections in a specific sequence. Vector search alone cannot do that.

The next architectural layer will address this. A graph-based retrieval approach can explicitly represent the relationships between statutory sections. It tracks which sections cross-reference which, which provisions depend on conditions established elsewhere, and which legal regimes take precedence. By combining this with a reasoning agent that plans a multi-step retrieval strategy before generating an answer, the system can begin to handle the kind of multi-condition questions that currently expose the ceiling of the vector approach.

This is not a complete redesign. The existing pipeline remains intact: the chunking strategy, the embeddings, and the reranking logic. The graph layer will sit alongside the vector store, and a reasoning layer will decide which retrieval path is appropriate for each query. When you build the foundation right, extending it becomes a product decision rather than a total rebuild.

---

What this taught me about AI in regulated domains

Coming from a background in business and finance rather than software engineering, I had to approach this architecture from first principles. I asked not how to build each component, but what each component needed to achieve. That constraint turned out to be useful. A few things are worth stating directly, because they get lost in most AI project write-ups.

The model is not the product. The retrieval architecture, the chunking strategy, the evaluation framework, and the honesty about scope: those are the product. The language model is one swappable component.

Demo quality and production quality are not the same thing. A system that produces plausible-looking answers in a demo can fail systematic accuracy review. The only way to know is to test it against the domain. There is no shortcut.

Scope discipline is a feature. A system that answers only what it knows, and says so clearly when it does not know, is more valuable than one that attempts to answer everything. This is true for AI systems and for consulting advice.

Privacy-preserving architecture is not a constraint. It is a competitive position. In regulated industries, the ability to deploy AI that keeps sensitive data on-premise is becoming a prerequisite, not a differentiator. Building with that assumption from the start is the right approach.

This project started as a personal tool for a personal problem. It became a useful exercise in what it actually takes to build an AI system that can be trusted in a domain where being wrong has consequences.

One thing worth being transparent about: the system design, architecture decisions, and testing were mine. The Python implementation was built using Claude Code and Gemini as coding assistants, working from the same architectural brief described in this post. That is also part of the point. You do not need to write every line yourself to understand what the system is doing and why.

I am still learning and exploring this space. If you have built something similar, spotted a better approach, or have thoughts on the architecture or the direction, I would genuinely like to hear it.

View on GitHub →

© 2026 Arnav Amal Ray. All rights reserved.

Building the finance bot our family actually uses every day

How a simple frustration with household expense tracking led to a serverless AI bot, and what it took to make something genuinely reliable rather than just technically interesting.

Most finance tracking systems have the same failure mode. They work beautifully for the person who set them up and nobody else. The categories are unfamiliar. The interface requires deliberate effort. The habit breaks within a week. The spreadsheet becomes a monument to good intentions.

My household runs on two people with different spending patterns, different contexts for each purchase, and a shared but loosely managed sense of where money goes each month. We had tried apps. We had tried shared Google Sheets. We had tried a period of determined discipline that lasted about three weeks before both of us stopped updating things.

The problem was never motivation. It was friction. Logging an expense needed to feel like sending a text, not filing a form. If it takes more than five seconds, it does not get done.

That is the constraint this project was built around. Not analytics richness. Not financial insight. Friction, first. Everything else second.

---

The obvious question

The obvious answer to household expense tracking in 2026 is to use one of the many apps built for exactly this purpose. They are polished, well-supported, and have years of iteration behind them. So why build something instead?

The short answer is that the apps solved a slightly different problem than the one I had. The long answer involves a few specific objections.

Shared apps require shared buy-in. Getting a second person to install something, create an account, and learn a new interface is a non-trivial ask. Telegram is already on both of our phones. The bot lives inside a conversation thread. There is nothing to install and nothing to learn. That removes the largest single barrier to consistent use.

Most apps require structured input. You tap a category, enter an amount, select a merchant from a dropdown, confirm. That is still a form, just a mobile one. The bot accepts a text message. "45 Rewe" is the entirety of what you need to type. The AI handles everything else. The interface is already a language model, which means the input can be as casual and unstructured as actual human speech.

The data is ours and it stays ours. Commercial apps aggregate usage data. They have terms of service. Some connect directly to bank accounts, which introduces a category of risk that I am not comfortable with for a household finance tool. Google Sheets is a place I control. The bot writes to it. Nobody else reads it.

The spreadsheet is still the interface for the people who need it. My family members who are not developers can open the Google Sheet, filter by month, and see exactly what was recorded. There is no proprietary format, no export step, and no lock-in. The underlying data is always plain and accessible.

Those four things together made building more attractive than buying, even accounting for the time it took.

---

The design brief

Before writing any code, I wrote down what the system had to do and, just as importantly, what it did not need to do.

It had to accept natural language expense input without any required structure. "15 lunch," "12,50 pizza," "655 ETF investment," and a photo of a supermarket receipt all had to produce the same clean, structured row in the spreadsheet. The AI had to make every categorisation and parsing decision without asking the user for clarification.

It had to be truly serverless. Not because of cost, though that mattered, but because a tool that requires a running server is a tool with a maintenance burden. Vercel functions cost nothing at household scale and require no operational attention. The bot either responds instantly or it does not respond at all. There is no degraded state to manage.

It had to work across family members without any synchronisation mechanism beyond the shared spreadsheet. Two people logging expenses from different phones at the same time needed to produce two separate rows without collision. Race condition handling was a requirement, not an afterthought.

It had to be honest about what it could not do. A bot that confidently parses a receipt incorrectly and saves wrong data is worse than one that asks you to try again. Validation checks on parsed amounts, categories, and dates were built into the pipeline before any data reaches the spreadsheet.

The goals feature came later, but it followed the same brief. Create financial and task goals using a single natural language message. View them without navigating away from the conversation. Mark them complete when done. No special syntax. No form filling.

---

Architecture decisions

The stack is deliberately minimal. Telegram handles the interface. Vercel handles the runtime. Google Sheets handles the database. Groq handles the AI inference. Each component does one thing well and passes its output to the next.

Why Telegram over a dedicated web interface. The framing that drove this decision was simple: the best interface is the one people already have open. Telegram is a conversation. Adding a finance bot to an existing conversation thread is zero marginal effort. A dedicated web app, even a well-designed one, is a tab you have to remember to open.

Why Groq over a local model. This system handles real-time conversational input. A user sends a message and expects a response within a second or two. Local inference at that latency requires hardware that a household setup does not have available for a lightweight task like expense parsing. Groq’s LPU inference returns in under a second even for vision tasks like receipt scanning. The data involved is a purchase amount and a merchant name. Sending that to a cloud API is a different data governance decision than sending an immigration law query. I made the trade-off consciously.

Why Google Sheets over a proper database. The “database” for a household finance tracker is used by non-technical family members who want to open a spreadsheet, scroll through January, and understand what they spent on groceries. A PostgreSQL instance is not accessible to those users without a purpose-built frontend. Google Sheets is. The entire value of the persistent store is its accessibility, and Sheets provides that natively. The trade-offs, including limited query expressiveness and race conditions on concurrent writes, were all solvable at household scale.

Why a single serverless file. A single-file serverless handler eliminates the overhead of module management, import resolution across deployment environments, and the cognitive load of navigating a project structure for what is fundamentally a straightforward routing and persistence task. The entire bot fits in one file. Every component of the system is visible at once.

---

How it works

The expense parsing prompt is where most of the system behaviour lives. It handles German decimal notation ("12,50" means 12.50 EUR, not 1250), local merchant shorthand ("DM" means dm-drogerie markt, not Deutsche Mark), and the full range of input formats a real user would actually type. The AI is instructed to return only valid JSON, to trust the exact number given without scaling it, and to default to "Other" rather than invent a category that does not exist. These rules are not clever. They are the result of actual failures in early testing that produced wrong data in the spreadsheet.

The goal parsing prompt has different challenges. It has to extract a deadline from natural language like "by next summer" or "in three months," classify the goal type from context, and decide whether something is a financial goal or a task based on whether it carries an amount. The AI is given the current date as context and instructed to return a null date rather than invent one when the input is ambiguous. A goal with no deadline is fine. A goal with a fabricated deadline is not.

The analytics engine runs on pandas. When a user calls /summary, the bot fetches the full Expenses sheet and caches the resulting DataFrame in memory for two minutes. This prevents repeated API calls to Google Sheets when family members hit the dashboard back-to-back, which would otherwise hit rate limits quickly. The dashboard uses Telegram’s inline keyboard to let users drill down without leaving the conversation. Clicking a user’s name opens their personal category breakdown. The interaction stays entirely within Telegram.

---

The quality gate

The most useful testing was simply using the bot daily. Real failures surfaced quickly: "655 investment ETF" parsed as 6.55 EUR; "DM" classified as Deutsche Mark rather than the drugstore chain. Each was a wrong row in the spreadsheet, which is worse than no row at all. The parsing rules were tightened in the prompt until the failures stopped.

Security and correctness required explicit attention. Webhook secret token validation, an entry-point allowlist, and formula injection stripping were all added after testing showed the gaps. The undo handler uses a timestamp re-fetch before deleting to avoid corrupting data when two people log expenses at the same moment.

---

What comes next

Two extensions are clearly defined.

The goals feature currently tracks flat lists. A more useful version would connect goal targets to actual spending patterns in the Expenses sheet. If you are saving for a trip and logging expenses consistently, the system should tell you whether your savings rate maps to your target date.

Multi-currency support is the more pressing gap. The household spans three currencies regularly: INR and USD from travel to India and the US, and CHF from occasional trips to Switzerland. All amounts are currently normalised to EUR at entry, which requires a manual conversion before typing. The fix is to detect the currency from the input, fetch an exchange rate at log time, and store both the original and the EUR equivalent.

---

What this taught me about building tools for actual use

A few things are worth stating plainly.

You do not need a frontend for a proof of concept. Telegram already existed on every phone in the household. Building inside it rather than building a new interface meant zero onboarding, no installation, and no habit to form. The tool gets used because it is already in a conversation thread people check anyway. The friction that stops a family member from logging a €15 lunch is the exact same friction that stops a sales team from updating their CRM. If the tool is not where the user already is, adoption fails regardless of how good the underlying system is.

Google Sheets is a legitimate persistence layer for personal tools. It is not a database. But for a household finance tracker, the value of the persistent store is that family members can open it directly, without going through the bot. Plain and accessible beats sophisticated and opaque.

Daily use is the only honest test. The parsing bugs that mattered did not appear in any test I designed. They appeared because the bot was used every day by real people. Ship to production early. That is where the real failures are.

The implementation was built using Claude Code as a coding assistant. The product decisions, prompt engineering, and architecture were mine.

© 2026 Arnav Amal Ray. All rights reserved.