Architecture overview

This document is a working description of how current tools fit together across front-ends, internal engines, and storage. It is intentionally general: specific edge cases and formulas live in per-system docs.

Top-level picture

Rough layers:

• Front-ends – Next.js (web tools), SwiftUI (iOS apps), simple static pages.
• Engines – logic layers and pipelines (SiteTax logic, Watermarkd rendering, future tools).
• Storage – local (SQLite) during development; Firestore or similar for live data; file exports (PDF, image, etc.).

front-end (Next.js / SwiftUI)
        ↓
internal engine (logic / pipeline)
        ↓
storage layer (SQLite / Firestore / file export)

Front-ends

Web

• Next.js for multi-screen tools, data flows, dashboards, or anything interactive.
• Static HTML for simple documentation surfaces (gmz.dev, internal notes, landing pages).
• Bias toward minimal UI so tools remain usable in field conditions (contractors, quick checks).

iOS

• SwiftUI for apps like Watermarkd and SiteTax.
• Application logic should live in separate types (view models, logic layers) rather than inside views.

Engines

Engines are where reasoning happens. They take plain structured inputs and return plain structured outputs, without knowing anything about UI or platform.

Examples

• SiteTax logic – receives job details and returns a taxable / non-taxable classification with a short explanation.
• Watermarkd pipeline – receives an image + overlay parameters and returns an export-ready image.
• Future tools – any logic that could be reused across web and iOS should live here, not inside UI code.

Rule of thumb: if something could be useful in more than one app, it should become an engine.

Storage

Current assumptions:

• SQLite for development and any tool that doesn't need sync or multi-device access.
• Firestore (or similar) for live tools requiring authentication, sync, or user data.
• Files (PDF, image exports) as output surfaces rather than primary storage.

Cross-cutting ideas

Error handling

• Prefer explicit errors ("missing tax rate") over hidden fallback behavior.
• Errors should be expressible in a UI-agnostic way so both web and iOS can present them cleanly.

Versioning

• When rules change (tax logic, image pipelines), track changes here or in per-system docs.
• It should remain possible to answer: “What logic produced this export/decision at that time?”

Where to go next

• SiteTax logic – specifics on NJ tax classification.