Features and Modules — ContaAutónomo capabilities

Expenses

Track expenses with file uploads, contractor links, multi-currency support and category filtering

Endpoints

• GET /expenses/
• GET /expenses/create
• POST /expenses/create
• GET /expenses/edit/</code></li>
• POST /expenses/edit/</code></li>
• POST /expenses/delete/</code></li>
• GET /expenses/file/</code></li>
• GET /expenses/download/</code></li>
• GET /expenses/preview/</code></li> </ul>

  Models

  • Expense
  • Contractor

  Features

  • Multi-currency expense entries with per-row exchange rate
  • Receipt attachments via FileStorageBackend (local, S3, GCS, GDrive)
  • Contractor relationships and category-based search
  • Quarterly grouping aligned with quarterly tax reporting
  • Contributes Expenses and VAT data to the Tax Obligations panel
  </section>

  Tax Management

  Manage Spanish tax forms (Modelo 349, 303, 130, 390, 100) and Social Security (autonomo) payments

  Endpoints

  • GET /tax-forms/
  • POST /tax-forms/upload
  • GET /tax-forms/download/</code></li>
  • GET /tax-forms/preview/</code></li>
  • POST /tax-forms/delete/</code></li>
  • POST /tax-forms/ss-payments/add
  • POST /tax-forms/ss-payments//edit</code></li>
  • POST /tax-forms/ss-payments//delete</code></li> </ul>

    Models

    • TaxForm
    • SSPayment

    Features

    • Upload and version Spanish Modelo PDFs (303, 130, 349, 390, 100)
    • Track Social Security (cuota autonomos) payments per month
    • Dashboard panel with annual SS totals and pending months
    • Quarterly grouping that mirrors AEAT submission deadlines
    • Inline preview and download for archived returns
    </section>

    Tax Poland (IT) Optional

    Polish tax rules for IT freelancers (JDG/B2B): flat 19% PIT or progressive 12%/32%, VAT 23%, ZUS

    Can be enabled or disabled in Settings without data loss.

    Endpoints

    No HTTP endpoints (data-only module).

    Models

    • TaxPolandConfig

    Features

    • Flat tax (19%) or progressive (12%/32%) PIT calculation
    • Health insurance: 4.9% on flat tax, 9% on progressive
    • Automatic VAT 23% (PTU) override on enable
    • Monthly ZUS social insurance with annual aggregation
    • Localized field labels (NIP, PESEL) for Polish freelancers

    Documents

    Store and manage documents with categories, tags, multi-file attachments, preview and download

    Endpoints

    • GET /documents/
    • GET /documents/create
    • POST /documents/create
    • GET /documents/edit/</code></li>
    • POST /documents/edit/</code></li>
    • GET /documents/view/</code></li>
    • POST /documents/delete/</code></li>
    • GET /documents/download/</code></li>
    • GET /documents/preview/</code></li>
    • GET /documents/file//download</code></li>
    • GET /documents/file//preview</code></li>
    • POST /documents/file//delete</code></li>
    • POST /documents/file//sign/</code></li>
    • GET /documents/categories
    • POST /documents/categories/add
    • POST /documents/categories//delete</code></li>
    • POST /documents/categories//color</code></li>
    • POST /documents/duplicate/</code></li>
    • POST /documents/bulk
    • POST /documents/note/add/</code></li>
    • POST /documents/note/edit/</code></li>
    • POST /documents/note/delete/</code></li> </ul>

      Models

      • Document
      • DocumentCategory
      • DocumentFile
      • DocumentConfig
      • DocumentHistory
      • DocumentNote

      Features

      • Multiple file attachments per document with size and format
      • Categories with custom colours and tag-based filtering
      • Per-document notes plus full audit history of changes
      • Inline preview, download and bulk operations
      • Auto-collected categories merged with manually managed ones
      </section>

      Backup & Restore

      Full encrypted backups (DB JSON + uploaded files) with daily scheduling and external storage

      Endpoints

      • POST /backup/
      • GET /backup/download/</code></li>
      • POST /backup/restore/</code></li>
      • POST /backup/delete/</code></li>
      • GET /backup/upload-restore
      • POST /backup/upload-restore
      • POST /backup/load-demo
      </ul>

      Models

      • BackupConfig

      Features

      • Single ZIP archive with DB dump and all uploaded files
      • Optional AES-256 encryption (app password or separate password)
      • Daily scheduled backups via TaskScheduler
      • Optional copy to External Storage (S3, GCS, Google Drive)
      • Restore from local backup, uploaded JSON, or demo dataset
      </section>

      Reports

      Generate professional financial reports (PDF) with selectable sections from any enabled module

      Endpoints

      • GET /reports/
      • POST /reports/generate
      • POST /reports/file-list

      Models

      No SQLAlchemy models.

      Features

      • Quarterly or full-year reports for income, expenses and SS
      • Pluggable sections via get_report_sections() from any module
      • Currency mode: original or converted to base currency
      • Optional ZIP bundle with attached source documents
      • Configurable PDF report templates (official, minimal, custom)

      External Storage Optional

      Route file storage to external backends: AWS S3, Google Cloud Storage or Google Drive

      Can be enabled or disabled in Settings without data loss.

      Endpoints

      • POST /storage/test

      Models

      • StorageConfig

      Features

      • Pluggable FileStorageBackend implementations
      • AWS S3 with profile, key-pair or default credentials
      • Google Cloud Storage and Google Drive with service accounts
      • Connection test directly from the settings UI
      • Transparent to other modules; uses core.storage API

      Invoice Attachments Optional

      Upload ready-made invoice PDFs from the invoice view, create or edit forms instead of generating them

      Can be enabled or disabled in Settings without data loss.

      Endpoints

      • POST /invoice-attachments/attach/</code></li> </ul>

        Models

        No SQLAlchemy models.

        Features

        • Attach an external PDF to any unlocked invoice
        • PDF upload field added to invoice create and edit forms
        • MIME validation and full audit logging on each upload
        • Replaces a generated PDF when one already exists
        </section>

        PDF Signature Optional

        Visual (image overlay) and digital (X.509/PFX) signing of invoice PDFs via pluggable capabilities

        Can be enabled or disabled in Settings without data loss.

        Endpoints

        • POST /pdf-signature/upload-file
        • GET /pdf-signature/preview-signature
        • POST /pdf-signature/sign/</code></li> </ul>

          Models

          • PDFSignatureConfig
          • PDFSignatureInvoice

          Features

          • Visual signature overlay with configurable position and size
          • Digital signing with X.509 PFX certificates via pyHanko
          • Capability provider for cross-module pdf_sign calls
          • Auto-detects pre-signed PDFs and badges them in the UI
          </section>

          PDF Signature Verify Optional

          Detect digital signatures in uploaded PDFs and display signer info (DocuSign, Adobe Sign, generic)

          Can be enabled or disabled in Settings without data loss.

          Endpoints

          • POST /pdf-verify/check
          • GET /pdf-verify/details

          Models

          No SQLAlchemy models.

          Features

          • Extract X.509 signer details from embedded PKCS#7 signatures
          • Inline Signed badges injected into file lists across modules
          • Full certificate chain with validity dates per signer
          • Capability provider for pdf_verify and file_badge integrations

          Invoice Comments Optional

          Add internal comments to invoices for tracking notes, reminders and communication history

          Can be enabled or disabled in Settings without data loss.

          Endpoints

          • POST /invoice-comments/add/</code></li>
          • POST /invoice-comments/delete/</code></li> </ul>

            Models

            • InvoiceComment

            Features

            • Comments are internal only and never appear on the PDF
            • Inline comments panel on the invoice view page
            • Initial-comment field injected into create and edit forms
            • Timestamped per comment with single-click delete
            </section>

            Invoice Designer Optional

            Visual UI for custom invoice PDF templates with block positioning, colours, fonts and label overrides

            Can be enabled or disabled in Settings without data loss.

            Endpoints

            • GET /invoice-designer/
            • GET /invoice-designer/create
            • POST /invoice-designer/create
            • GET /invoice-designer/edit/</code></li>
            • POST /invoice-designer/edit/</code></li>
            • POST /invoice-designer/delete/</code></li>
            • POST /invoice-designer/duplicate/</code></li>
            • GET /invoice-designer/preview/</code></li>
            • POST /invoice-designer/import
            • GET /invoice-designer/export/</code></li> </ul>

              Models

              • InvoiceTemplate

              Features

              • Grid layout with top, header, subtotal, bottom and footer slots
              • Per-block colours, fonts, label overrides and offsets
              • Six layout presets plus a live PDF preview
              • Import and export templates as JSON
              • Multiple templates selectable from invoice settings
              </section>

              AI Document Parser Optional

              AI-powered parsing of invoices and expenses (OpenAI GPT-4o, Anthropic Claude, Google Document AI)

              Can be enabled or disabled in Settings without data loss.

              Endpoints

              • GET /ai-parser/
              • POST /ai-parser/parse

              Models

              • AIParserConfig

              Features

              • Pluggable providers: OpenAI, Anthropic, Google Document AI
              • Auto-fills invoice and expense forms from parsed JSON
              • Per-provider credentials stored in settings
              • Supports PDF, JPEG and PNG document uploads
              • Activity log entry for every parse attempt

              OAuth Authentication Optional

              Pluggable OAuth provider (Google, GitHub) registered through BaseModule.get_auth_providers hook

              Can be enabled or disabled in Settings without data loss.

              Endpoints

              • GET /auth/oauth/login/</code></li>
              • GET /auth/oauth/callback/</code></li> </ul>

                Models

                • OAuthAccount

                Features

                • Implements the AuthProvider interface from core auth_routes
                • Multiple providers can be enabled simultaneously
                • Account linking with existing local users
                • Stateless and removable without affecting core auth
                </section> ## Multi-currency support ContaAutónomo supports invoices and expenses in multiple currencies through the `CurrencyService` core service (see [Architecture → Core services](/architecture/#currency_service)). Exchange rates come from the European Central Bank (ECB) reference feed by default, which exposes more than 50 currencies; alternative providers can be registered via `CurrencyService.set_provider(...)` without touching modules. How it works in practice: - Each invoice and expense stores both the **original amount and currency** entered by the user and a **converted amount in the base currency** (typically EUR). The conversion uses `CurrencyService.convert(amount, from_currency, to_currency, date_str)`. - Rates are looked up by document date (not "now"), so historical reports remain stable even when newer rates arrive. - Daily ECB rates are fetched and cached automatically. The Reports module switches between original-currency and converted-currency views with a single toggle. - If the active provider fails, the service transparently falls back to ECB so freelancers can keep working offline-of-third-parties. ## Security Security mechanisms are layered across the framework, not bolted onto a single module: - **CSRF protection** — Flask-WTF tokens are issued for every form-rendered page and verified on all state-changing POST endpoints. The token is bound to the session. - **Rate limiting** — per-IP, per-route throttling on authentication and write endpoints (login, password reset, AI parser, file uploads) blunts brute-force and abuse without affecting normal browsing. - **Security headers** — every response carries a Content Security Policy (CSP), `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`, and a strict `Referrer-Policy`. Together they reduce XSS, clickjacking and MIME-sniffing risk. - **AES-256 backup encryption** — the Backup module produces ZIP archives encrypted with AES-256 keys derived via PBKDF2 from either the application password or a separate, user-chosen backup password. Encrypted archives are safe to copy to External Storage (S3, GCS, Google Drive). ## Task Scheduler The `TaskScheduler` core service runs a single in-process daemon thread and exposes a small API to modules (see [Architecture → Core services](/architecture/#scheduler)). Modules register periodic work during their `on_enable` (or comparable) hook: ```python core.scheduler.add_job( job_id="backup.daily", func=run_daily_backup, job_type="daily", time_str="03:00", description="Encrypted daily backup of DB and uploaded files", ) ``` Two job types are supported: - `daily` — runs once per day at `time_str` (HH:MM, server local time). Used by the Backup module for nightly encrypted snapshots. - `interval` — runs every `interval` seconds. Used for log cleanup, cache warming, and similar housekeeping work. `scheduler.get_jobs()` returns each registered job with its id, type, schedule, last run, next run, running flag and last error — feeding the Settings UI so administrators can see what is scheduled and whether it is healthy.