VZGplattform / Horizon by VZG
Bilingual Bulgarian/German financial and administrative assistant for people living in Germany. The application helps users understand contracts and official documents, discover relevant benefits and savings opportunities, track deadlines, and prepare next actions in a clear, user-controlled workflow.
Product status: V1 foundation for private customers. The application provides information and document preparation; it is not a tax adviser, lawyer, insurance broker, or official authority.
Highlights
- Bulgarian and German UI with locale-aware routes (
/bg/... and /de/...).
- Authentication and profiles backed by Supabase, including Google OAuth support.
- Contract and document workflows for upload, OCR, extraction, review, and signed downloads.
- Benefits and tax-oriented flows including Kindergeld, Finanzamt requests, tax questionnaire and PDF preparation.
- Contract Radar for structured contract reviews, deadlines, history, and user-approved next steps.
- Office workspace for case-based document and correspondence workflows.
- Financial education content and deterministic opportunity calculations.
- PWA support with install metadata and a service worker.
- Production health endpoint:
/api/health.
Technology
| Area | Technology |
|---|
| Application | Next.js 16, React 19, TypeScript |
| Styling and UI | Tailwind CSS 4, shadcn/ui primitives, Lucide |
| Internationalization | next-intl, Bulgarian (bg) and German (de) |
| Authentication and data | Supabase Auth, PostgreSQL, Storage, RLS |
| AI and document processing | Groq-compatible AI integration, OCR, PDF.js, Tesseract.js |
| Validation and tests | ESLint, TypeScript, Vitest, repository i18n checks |
| Package manager | pnpm |
| Deployment | Render via GitHub main branch |
Quick start
Requirements
- Node.js 22 or a compatible modern Node.js release
- pnpm 11+
- A Supabase project for authentication and protected features
Install and run
pnpm install
cp .env.example .env.local
pnpm dev
Open http://localhost:3000. Bulgarian and German routes are available under /bg and /de.
Production build locally
pnpm build
pnpm start
Environment variables
Copy .env.example to .env.local. Never commit .env.local, service-role credentials, OAuth secrets, or webhook secrets.
| Variable | Required for | Description |
|---|
NEXT_PUBLIC_SUPABASE_URL | Auth and data | Supabase project URL |
NEXT_PUBLIC_SUPABASE_ANON_KEY | Auth and data | Public Supabase anon key |
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY | Alternative | Public publishable key, where used by the project |
SUPABASE_SECRET_KEY | Server-side operations | Server-only Supabase secret/service key; never expose it to the browser |
NEXT_PUBLIC_DEV_SUPABASE_REDIRECT_URL | Local OAuth | Local callback URL, normally http://localhost:3000/auth/callback |
GROQ_API_KEY | AI features | Server-side AI provider key |
AUTOMATION_WEBHOOK_URL | Offer requests | Automation webhook URL (currently Activepieces Cloud) |
AUTOMATION_WEBHOOK_SECRET | Offer requests | Shared secret used to authenticate webhook delivery |
Public pages and /api/health can run without Supabase configuration. Protected routes and integrations require the relevant variables and return a controlled configuration error when they are unavailable.
Common commands
| Command | Purpose |
|---|
pnpm dev | Start the development server |
pnpm build | Create a production build |
pnpm start | Serve the production build |
pnpm lint | Run ESLint |
pnpm typecheck | Run TypeScript without emitting files |
pnpm test | Run the Vitest suite |
pnpm i18n:verify | Check translation parity, usage, and hardcoded strings |
pnpm supabase:check | Validate the configured Supabase project |
node scripts/terra-preflight.mjs | Check Terra/tool readiness before assigned work |
Recommended pre-commit verification:
pnpm i18n:verify
pnpm typecheck
pnpm lint
pnpm test
Project structure
app/ Next.js App Router pages and API routes
components/ Shared UI and feature components
i18n/ Locale routing and request configuration
lib/ Domain logic, Supabase helpers, validation, and services
messages/ Bulgarian and German translation dictionaries
public/ PWA assets, icons, and service worker
scripts/ Local validation and readiness scripts
supabase/ Migrations, functions, prepared SQL, and RLS tests
docs/ Product plans, operating notes, and technical scope
proxy.ts Locale and request proxy
Database and Supabase
Migrations live in supabase/migrations. Apply them through the Supabase CLI in the intended environment; do not edit production tables manually or disable Row Level Security as a shortcut.
supabase link --project-ref <project-ref>
supabase db push
Review migration SQL and RLS policies before applying changes to a shared or production project. The repository also contains prepared SQL and RLS tests that are not automatically applied by the normal migration flow.
Deployment
The production service is deployed from the GitHub main branch to Render. A normal deployment flow is:
- Run the local verification commands.
- Commit a focused change to a branch or
main, according to the repository workflow.
- Push to GitHub and wait for Render to finish the automatic deployment.
- Verify the health endpoint and the relevant localized route.
Production checks:
curl -i https://vzgplattform.onrender.com/api/health
curl -I https://vzgplattform.onrender.com/bg/auth/login
curl -I https://vzgplattform.onrender.com/de/auth/login
Documentation
Security and data handling
Treat uploaded documents, financial profiles, authentication data, and extracted facts as sensitive. Keep secrets server-side, use least-privilege Supabase access, preserve RLS policies, validate webhook signatures, and avoid logging customer content or credentials. Changes affecting authentication, database schema, access policies, payments, or production data require an explicit review.
License
This repository is proprietary and all rights are reserved. No permission is granted to use, copy, modify, publish, distribute, sublicense, or sell any portion of the software without prior written permission from the copyright holder. See LICENSE for the full terms.
Disclaimer
VZGplattform / Horizon by VZG provides informational support and document preparation. It does not replace professional tax, legal, insurance, or government advice. Official decisions remain with the competent authorities.
