Elefthero - Open Invoicing for Greece

Open-source, self-hosted AADE myDATA invoicing for Greek small businesses -bilingual, transparent, and designed to keep data, XML, and costs under the owner’s control.

Comment

Inspiration

In Greece, small businesses must transmit invoice data to AADE myDATA. Yet the software available to them can be expensive, opaque, or shaped around contracts and workflows that do not fit a freelancer, local shop, or small family business.

Elefthero - Greek for “free” - began with a simple belief: meeting a public compliance obligation should not require giving up control of your own business data. An owner should be able to see what was sent, understand why something was rejected, keep records locally, and discuss them clearly with an accountant.

What it does

Elefthero is a self-hosted, bilingual Greek invoicing application built around a focused set of everyday AADE myDATA workflows: sales invoices, service invoices, retail receipts, and credit documents.

It lets a business create multi-line invoices, manage series and numbering, apply VAT and exemption reasons, choose payment methods, and provide the required income and E3 classifications. It validates Greek VAT numbers through VIES, stores reusable client details, and can enrich client data through the public ΓΕΜΗ - GEMI service when available.

Elefthero generates myDATA XML, sends it to AADE Test or Production, and retains the result: sent XML, received XML, UID, ΜΑΡΚ, QR URL, status, and developer log. It also provides inline PDF invoices, reusable templates, invoice reuse, client analytics, manual invoice email delivery, user roles, optional TOTP 2FA, encrypted settings, configurable login rate limiting, and accessibility controls.

Elefthero also includes an optional Viva.com POS workflow for events and in-person sales. It verifies incoming Viva payment webhooks against the configured merchant and selected live terminal, uses a single-line POS template to calculate VAT-exclusive values from Viva’s VAT-inclusive amount, creates an AADE-ready retail receipt, and retains the transaction audit trail. Businesses can review the draft first or explicitly enable automatic AADE submission.

How we built it

We built Elefthero with Python, Flask, SQLite, Jinja, Tailwind CSS, ReportLab, Cloudflare Tunnel, VIES, ΓΕΜΗ, Resend, Viva.com POS webhooks, and the AADE myDATA REST/XML API.

OpenAI Codex and GPT-5.6 were implementation partners throughout the project. We used them to build the Flask data model, first-run setup, encrypted secret storage, user management, invoice workflows, PDF generation, AADE XML builder, audit logs, Cloudflare deployment, and the product interface.

For the POS workflow, Codex helped us connect Viva’s documented webhook verification, OAuth transaction retrieval, live-terminal selection, idempotent transaction handling, VAT-inclusive payment calculation, and PDF payment references including TID, RRN, order code, masked card number, and authorization ID.

Most importantly, we used Codex iteratively with real AADE Test responses. Instead of treating validation errors as opaque failures, we turned them into concrete improvements in XML generation and pre-submit validation.

Challenges we ran into

AADE myDATA is strict: namespaces, XML element order, payment-method nesting, mandatory currency, counterpart rules, income-classification schemas, and invoice-type-specific restrictions all matter.

We encountered real validation errors around issuer and counterpart structure, totals, retail restrictions, payment methods, currency, and income classifications. Each error required careful reading of the AADE documentation, inspection of the exact XML payload, and a focused code correction.

Another challenge was product design. Compliance software needs technical depth, but a small-business owner should not need to become an XML expert. We worked to make the invoice flow simple while keeping the full sent and received XML trail available for debugging and accountant review.

Payment automation introduced a different kind of challenge: a webhook alone cannot be trusted as proof of a financial transaction. We designed the Viva flow to validate the selected terminal and merchant, retrieve the transaction directly from Viva, avoid duplicate processing, retain received webhook payloads, and keep automatic AADE submission opt-in.

Accomplishments that we're proud of

  • A working, self-hosted application with real AADE Test and Production modes—not a mockup.
  • A deliberately focused set of common small-business invoice workflows instead of an overwhelming enterprise catalogue.
  • Transparent sent and received AADE XML logs, so the integration is inspectable rather than a black box.
  • Storage and display of AADE UID, ΜΑΡΚ, QR URL, status, and generated PDFs after transmission.
  • Reusable clients with VIES validation, optional ΓΕΜΗ enrichment, addresses, filters, pagination, and per-client invoice analytics.
  • Professional inline PDFs with business identity, customer details, line-level VAT, payment method, notes, UID, ΜΑΡΚ, and clickable AADE QR links.
  • Security features including encrypted local secrets, CSRF protection, configurable login rate limiting, optional Turnstile, local roles, and optional authenticator-app 2FA.
  • A guided, privacy-safe demo mode with locally generated open-source narration and MP4 export for the Devpost presentation.
  • A public MIT-licensed repository built around freedom, openness, accessibility, and self-hosting.
  • Optional Viva.com POS automation for event and in-person payments, with separate Demo and Production credentials.
  • Terminal-restricted and server-verified Viva webhooks, with duplicate protection and readable retained webhook logs.
  • VAT-inclusive Viva payment totals converted into AADE-ready net/VAT amounts using a focused POS receipt template.
  • PDFs that retain relevant payment references: Viva Transaction ID, TID, RRN, Order Code, masked card number, and Authorization ID.
  • Invoice filters that distinguish Viva POS automated invoices from manually created invoices.

What we learned

We learned that reliable financial software depends on transparency as much as connectivity. A successful API submission is not enough: people need to understand the document, inspect the evidence, and recover gracefully when validation fails.

We also learned how powerful Codex can be as an iterative engineering partner. It helped transform real AADE validation responses into schema-aware fixes, move quickly across backend, frontend, deployment, and documentation work, and keep security and usability in view while the product evolved.

We learned that payment automation must be designed conservatively: verify the provider’s transaction server-side, make automated submission explicit, preserve an audit trail, and give the business a clear way to find and inspect automated documents later.

What's next for Elefthero

Next, we want to expand carefully rather than lose the simplicity that defines Elefthero. Planned directions include additional AADE workflows that need special data, recurring invoices, import and export tools, richer reporting, accountant collaboration, clearer Greek-language guidance for classifications, and automated XML schema regression tests.

We also want to improve onboarding for first-time business owners, so compliance feels less intimidating while preserving the principle at the heart of Elefthero: the business should control, understand, and retain its own invoicing data.

Built With

Share this project:

Updates