{"id":51594244,"url":"https://github.com/yvniel09/fintral-app","last_synced_at":"2026-07-11T17:01:31.773Z","repository":{"id":368519145,"uuid":"1285543741","full_name":"yvniel09/fintral-app","owner":"yvniel09","description":"Production SaaS for DGII fiscal compliance in Dominican Republic. e-CF, NCF, Reporte 606, AI assistant. Next.js 15 + FastAPI + PostgreSQL.","archived":false,"fork":false,"pushed_at":"2026-07-01T00:38:47.000Z","size":30,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-01T01:11:16.614Z","etag":null,"topics":["dgii","dominican-republic","electronic-invoicing","fastapi","fiscal-compliance","nextjs","postgresql","python","redis","saas","tax","typescript"],"latest_commit_sha":null,"homepage":"https://www.fintral.app","language":null,"has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yvniel09.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-30T23:11:49.000Z","updated_at":"2026-07-01T00:38:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yvniel09/fintral-app","commit_stats":null,"previous_names":["yvniel09/fintral-app"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/yvniel09/fintral-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yvniel09%2Ffintral-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yvniel09%2Ffintral-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yvniel09%2Ffintral-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yvniel09%2Ffintral-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yvniel09","download_url":"https://codeload.github.com/yvniel09/fintral-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yvniel09%2Ffintral-app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35368768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dgii","dominican-republic","electronic-invoicing","fastapi","fiscal-compliance","nextjs","postgresql","python","redis","saas","tax","typescript"],"created_at":"2026-07-11T17:01:29.639Z","updated_at":"2026-07-11T17:01:31.760Z","avatar_url":"https://github.com/yvniel09.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fintral\n\n**Automated fiscal compliance for the Dominican Republic.** e-CF generation, NCF management, Reporte 606 filing, DGII validation, and AI-powered tax assistance.\n\n[![CI](https://github.com/yvniel09/fintral-app/actions/workflows/ci.yml/badge.svg)](https://github.com/yvniel09/fintral-app/actions)\n[![Website](https://img.shields.io/badge/fintral.app-38BDF8?style=flat-square\u0026logo=nextdotjs\u0026logoColor=white)](https://www.fintral.app)\n[![Stack: Next.js + FastAPI](https://img.shields.io/badge/Stack-Next.js_15_•_FastAPI_•_PostgreSQL-09090b?style=flat-square)](https://github.com/yvniel09/fintral-app)\n\n---\n\n## The Problem\n\nThe Dominican Republic's **DGII** (Dirección General de Impuestos Internos) mandates electronic invoicing (e-CF) for all tax-registered businesses. The ecosystem is fragmented:\n\n- **No unified API** — e-CF generation, NCF control, and Reporte 606 are separate systems with different formats\n- **Proprietary XML signing** — requires XAdES-BES digital signatures compliant with DGII's specific schema\n- **Web-scraped validation** — DGII's public portal is an ASP.NET WebForms app with `__VIEWSTATE` tokens and no documented API\n- **Strict deadlines** — Reporte 606 must be filed monthly with penalties for late submissions\n- **Multi-entity chaos** — accounting firms manage dozens of clients, each with unique NCF ranges and fiscal regimes\n\nFintral solves this by providing a **single platform** that abstracts all DGII complexity behind a clean SaaS interface.\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────────┐\n│                     Nginx (Proxy)                      │\n│    ┌──────────────┐            ┌──────────────────┐   │\n│    │  Next.js 15   │◄─────────►│   FastAPI (Py)    │   │\n│    │  App Router   │  REST/WS  │   Clean Arch      │   │\n│    │  shadcn/ui    │           │   Repository      │   │\n│    │  Tailwind     │           │   Service Layer   │   │\n│    └──────┬───────┘           └────┬───┬───────────┘   │\n│           │                        │   │               │\n│           │                 ┌──────┘   └──────┐        │\n│           │                 ▼                  ▼        │\n│           │          ┌──────────┐      ┌──────────┐    │\n│           │          │PostgreSQL│      │  Redis   │    │\n│           │          │ (5440)   │      │ (6381)   │    │\n│           │          └──────────┘      └──────────┘    │\n└───────────┼────────────────────────────────────────────┘\n            │\n     ┌──────┴────────────────────────────────────┐\n     ▼                    ▼                       ▼\n┌──────────┐    ┌──────────────┐    ┌──────────────────┐\n│ Alanube  │    │  DGII Portal │    │  Intuit / Xero   │\n│ (e-CF    │    │ (web scrape) │    │  (accounting      │\n│  backend)│    │  + QR scan   │    │   integration)    │\n└──────────┘    └──────────────┘    └──────────────────┘\n```\n\n### Why FastAPI + Next.js?\n\n- **FastAPI** provides Python's rich ML/OCR ecosystem (OpenCV, Tesseract, pyzbar) for document processing — critical for invoice data extraction from photos, PDFs, and scanned QR codes\n- **Next.js 15 App Router** gives us React Server Components for SEO (public landing, docs) and client components for the dashboard — no context-switching between frameworks\n- **Dual auth (Supabase + bcrypt)** — Supabase handles social login and session management; bcrypt fallback ensures zero external dependency for core authentication during development and self-hosted deployments\n\n### DGII Integration Strategy\n\nThe DGII has no official API, so we use three complementary approaches:\n\n| Approach | What | Technique | Anti-blocking |\n|----------|------|-----------|---------------|\n| **Alanube API** | e-CF generation \u0026 submission | REST API with JWT auth (reseller model, ~$0.0088/doc overage) | Telemetry per call |\n| **DGII Web Scraper** | NCF physical validation | ASP.NET WebForms scraper (`__VIEWSTATE` extraction) | 500ms rate limit, on-demand only, result caching |\n| **QR Code Validation** | e-CF authenticity check | Multi-strategy CV: CLAHE, upscaling, OTSU, pyzbar | 10 strategies cascade |\n\nThe QR validation engine alone uses **10 fallback strategies** (CLAHE contrast enhancement, multi-scale upscaling, adaptive thresholding, morphological closing, pyzbar with 7 preprocessing variants) to decode real-world QR codes from photos with poor lighting, blur, or angled capture.\n\n## Key Features\n\n### Electronic Invoicing (e-CF)\n- Generates signed XML invoices compliant with DGII e-CF schema (XAdES-BES)\n- Alanube reseller backend with pooled document quotas across entities\n- Telemetry-tracked submission pipeline with automatic retries\n- Supports NCF types: 01 (final consumer), 02 (credit note), 04 (debit note), 11 (minor expenses), 12 (e-CF unique), 14 (savings), 15 (guest)\n\n### NCF Management\n- Track NCF ranges per entity with automatic consumption tracking\n- Real-time balance alerts when ranges approach depletion\n- Integration with DGII portal for NCF status validation (active/cancelled/voided)\n- Server Action pattern to bypass CORS on DGII web scrape calls\n\n### Reporte 606 / 607 / 608\n- Auto-generate monthly fiscal reports from invoice data\n- Excel export with DGII's required column format\n- NCF-by-NCF validation against DGII records before submission\n- Support for credit notes and cancelled invoice reconciliation\n\n### AI Tax Assistant\n- Context-aware chat over the full fiscal compliance lifecycle\n- Powered by Google Gemini 2.5 Flash (multi-provider abstraction via `LLMProvider` ABC)\n- RAG over user's own invoice history for personalized responses\n- Answers queries like \"What NCF type do I need for professional services?\" or \"Why was my e-CF rejected?\"\n\n### Multi-Entity \u0026 Team Management\n- Single account manages multiple RNCs (business entities)\n- Granular RBAC: owner, admin, member roles\n- Pooled e-CF quotas across entities under one subscription\n- Audit log for all compliance actions (who submitted what, when)\n\n### Accounting Integrations\n- **QuickBooks Online** — Push vendor bills via OAuth 2.0 (`com.intuit.quickbooks.accounting` scope)\n- **Xero** — API-based invoice synchronization\n- **Odoo** — ERP connector module\n\n### WhatsApp Invoicing\n- Accept invoice photos via WhatsApp (Evolution API gateway)\n- Multi-strategy OCR: OpenCV preprocessing → LLM vision extraction → structured data\n- Automatic duplication detection via Redis\n- Supabase Storage for uploaded file archival\n\n## Technical Decisions \u0026 Trade-offs\n\n### Server Actions as CORS Proxy\nDGII's portal doesn't support CORS. Instead of a dedicated proxy service, we use **Next.js Server Actions** (`consultRncAction`, `searchByNameAction`) as the CORS bridge. This eliminates an extra hop while keeping secrets server-side.\n\n### Invoice Processing Pipeline\nA modular pipeline with pluggable stages — each stage can be maintained and tested independently:\n\n```\nImage Preprocessor → Classifier (e-CF / PDF / Photo / XML)\n  → Normalizer → AI Extractor (LLM vision fallback)\n  → Post-Extraction Validator → Categorizer\n  → Pipeline Orchestrator\n```\n\nThe pipeline includes OCR character corrections (`O→0`, `I→1`, `S→5`, etc.) tailored to invoice scans, and cascading from high-confidence structured extraction → LLM vision → full OCR.\n\n### PWA Offline Support\nUsing **Serwist** (workbox fork) for service worker caching, plus **Dexie.js** (IndexedDB) for offline invoice data — the app works without connectivity and syncs when back online.\n\n### Cost Control Architecture\nUsage tracking is baked into every operation. AI chat has hard caps per plan; e-CF overage uses soft limits (never blocks — sends warning). Redis-backed rate limiting on WhatsApp ingestion prevents runaway costs.\n\n## Engineering Practices\n\n- **CI/CD**: GitHub Actions runs lint (ESLint + Ruff), TypeScript type-check, build, and pytest on every PR\n- **Pre-push hooks**: Local CI via `act` before pushing, skippable with `--no-verify`\n- **Testing**: 20+ backend test files covering pipeline processing, DGII validation, AI chat, webhooks, exports, and QR validation\n- **Conventional commits**: `type(scope): description` format across all history\n- **TypeScript strict mode**: `tsc --noEmit` in CI\n- **React Doctor**: Automated component diagnostics via `react-doctor`\n- **pnpm**: Fast, disk-efficient package management with frozen lockfiles\n\n## Project Structure\n\n```\nfrontend/                         # Next.js 15 App Router\n├── app/\n│   ├── dashboard/               # Main dashboard pages\n│   ├── dgii-rnc/                # RNC validation \u0026 DGII consultation\n│   ├── upload/                  # Invoice upload portal\n│   ├── billing/                 # Subscription management\n│   ├── actions/                 # Server Actions (CORS proxy)\n│   └── auth/                    # Supabase + bcrypt login\n├── features/\n│   ├── dgii/                    # Reporte 606/607/608 features\n│   ├── invoices/                # Invoice management\n│   ├── store/                   # POS / store checkout\n│   ├── chat/                    # AI tax assistant\n│   └── dashboard/               # Analytics widgets\n├── components/ui/               # shadcn/ui components\n└── lib/\n    ├── api/                     # API client layer\n    └── services/                # Client services (DGII, etc.)\n\nbackend/                         # FastAPI\n├── app/\n│   ├── core/                    # Redis, auth, permissions, DI container\n│   ├── models/                  # SQLAlchemy models\n│   ├── services/\n│   │   ├── alanube.py           # e-CF API reseller client\n│   │   ├── dgii_scraper.py      # DGII WebForms scraper\n│   │   ├── dgii_validation.py   # QR validation (10 strategies)\n│   │   ├── pipeline/            # Invoice processing pipeline stages\n│   │   ├── pipeline_orchestrator.py\n│   │   ├── quickbooks_connector.py\n│   │   ├── xero_connector.py\n│   │   ├── whatsapp.py          # WhatsApp + OCR ingestion\n│   │   ├── llm_providers.py     # Abstract LLM provider interface\n│   │   └── ai_chat_service.py   # AI assistant backend\n│   ├── routers/                 # API endpoints\n│   └── utils/                   # Date parsing, etc.\n├── tests/                       # 20+ test files\n└── Dockerfile\n\ninfra/\n├── compose.yml                  # PostgreSQL + Redis + Nginx\n├── docker-compose.dev.yml\n├── nginx/                       # Reverse proxy config\n└── scripts/                     # Setup, invitations, DB seeding\n```\n\n## Getting Started (Development)\n\n```bash\n# Clone\ngit clone https://github.com/yvniel09/fintral-app.git\ncd fintral-app\n\n# Backend\ncd backend\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -r requirements-dev.txt\ncp .env.example .env          # Configure your environment\nuvicorn app.main:app --reload --port 8000\n\n# Frontend\ncd frontend\npnpm install\npnpm dev                      # → http://localhost:3000\n\n# Or use Docker\ndocker compose -f compose.yml up\n```\n\n## What Makes This Project Interesting\n\n- **Real production SaaS** — not a demo or tutorial. Handles real DGII compliance for Dominican businesses\n- **Solves a genuine infrastructure gap** — DR's tax authority has no API, so we built our own integration layer\n- **Full-stack engineering** — from OpenCV image processing to multi-provider LLM abstraction to React Server Components\n- **Pragmatic trade-offs** — chose Server Actions over a dedicated proxy, dual auth over lock-in, pooled NCF quotas over per-entity billing\n- **Design-conscious** — the UI is inspired by Stripe's design system with deliberate typography, color, and spacing decisions documented in `DESIGN.md`\n\n## Pricing\n\n| Plan | Price | e-CF | AI Queries | Users |\n|------|-------|------|------------|-------|\n| **Esencial** | $29/mo | 50 | 300 | 2 |\n| **Profesional** | $69/mo | 300 | 3K | 5 |\n| **Multi-Entidad** | $149/mo | 5K pooled | 10K | 10 entities |\n| **Enterprise** | $299+/mo | Custom | Custom | Custom |\n\n15-day free trial on all plans.\n\n---\n\n*Built for Dominican Republic businesses navigating DGII fiscal compliance.*\n\n[![Website](https://img.shields.io/badge/fintral.app-38BDF8?style=flat-square\u0026logo=nextdotjs\u0026logoColor=white)](https://www.fintral.app)\n[![GitHub](https://img.shields.io/badge/GitHub-yvniel09-09090b?style=flat-square\u0026logo=github)](https://github.com/yvniel09)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyvniel09%2Ffintral-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyvniel09%2Ffintral-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyvniel09%2Ffintral-app/lists"}