10scoops/german-residence-permit-assistant

AI-powered assistant that helps immigrants fill out German residence permit (Aufenthaltstitel) applications in their native language. Supports Arabic, Farsi, Ukrainian, Somali, and 10+ more languages. Built with React, Supabase, and Gemini AI. # German Residence Permit Assistant An AI-powered tool for navigating the German residence permit application process. It asks users the right questions in their native language, handles the complexity of conditional form logic, and produces a filled PDF ready to hand in at the Ausländerbehörde. ## Features - **Multilingual** — supports 15+ languages including Arabic, Somali, Tigrinya, Kurdish, Pashto, Ukrainian, and more - **AI-powered card scanning** — scan the front and back of a residence card to auto-fill form fields - **Smart form flow** — conditional questions based on previous answers, with the ability to skip and return to unanswered questions - **Contextual help** — AI-generated explanations for each question in the user's language - **PDF generation** — produces a filled *Antrag auf Aufenthaltstitel* PDF ready for submission - **Demo mode** — try the app without real credentials using sample data ## Prerequisites - Node.js 18+ (or Bun) - A Supabase project with the edge functions deployed (see supabase/) - A contact email for the "send by email" feature The following are only needed for running translation and PDF-mapping scripts, not for running the app itself: - Google Cloud Translation API key - Google Gemini API key ## Setup **1. Clone the repo and install dependencies** ```sh git clone cd residency-assistant npm install ``` **2. Configure environment variables** Copy `.env.example` to `.env.local` and fill in your values: ```sh cp .env.example .env.local ``` | Variable | Required | Description | |---|---|---| | `VITE_SUPABASE_URL` | Yes | Your Supabase project URL | | `VITE_SUPABASE_PUBLISHABLE_KEY` | Yes | Your Supabase anon/public key | | `VITE_CONTACT_EMAIL` | Recommended | Email shown in the "send application" button | | `VITE_DEMO_MODE` | No | Set to `true` to use sample data without Supabase | | `VITE_CLOUD_TRANSLATE_API_KEY` | Scripts only | Google Cloud Translate (for `npm run translate:*`) | | `VITE_GEMINI_API_KEY` | Scripts …