# CHEQUE.IO — Technical Architecture

## Purpose
Documents the technical architecture, design decisions, data flow, and technology stack of CHEQUE.IO.

## Stack
| Layer | Technology |
|-------|-----------|
| **Structure** | HTML5 |
| **Styling** | CSS3 with custom properties (CSS variables) |
| **Logic** | Vanilla JavaScript (ES6+) |
| **Persistence** | Browser `localStorage` API |
| **Printing** | Browser `window.print()` with `@media print` CSS |
| **Testing** | Playwright (E2E) |
| **Deployment** | Vercel (static hosting) |
| **Version Control** | Git / GitHub |

## Why Vanilla JS?

CHEQUE.IO deliberately uses zero npm runtime dependencies. Rationale:
1. **Zero supply chain risk**: No third-party packages that can introduce vulnerabilities or breaking changes.
2. **Performance**: No framework overhead. First contentful paint is near-instant.
3. **Longevity**: Vanilla HTML/CSS/JS has no deprecation risk. The application will work in any browser, indefinitely.
4. **Auditability**: Any developer can read and audit the entire codebase without framework knowledge.

## Client-Side Architecture

```
Browser
│
├── index.html          — SPA shell, section views
├── index.css           — All styling, CSS custom properties, @media print
├── app.js              — All application logic
│   ├── Data Layer      — CRUD operations on localStorage
│   ├── View Layer      — DOM manipulation, tab switching
│   ├── Print Layer     — Cheque layout generation, offset calculations
│   └── Report Layer    — Analytics aggregation, filter logic
│
└── localStorage
    └── chequeio_records[] — Array of ChequeRecord objects
```

## Data Flow

### Issue Cheque Flow
```
User fills form
    → Form validation (HTML5 required attributes)
    → ChequeRecord object created with timestamp ID
    → Record appended to localStorage array
    → Table row injected into DOM
    → Print dropdown updated
```

### Print Flow
```
User selects cheque from dropdown
    → ChequeRecord loaded from localStorage
    → Bank template selected → layout constants loaded
    → X/Y offsets applied to absolute positions
    → Amount-in-words conversion triggered
    → Preview div populated with absolutely positioned spans
    → User clicks Print → window.print() called
    → @media print CSS hides all non-printable elements
    → Browser sends printable area to OS print dialog
```

### Report Flow
```
Month/Year filters changed
    → All records loaded from localStorage
    → Filtered by selected month/year
    → Aggregated: sum, count, avg, max
    → Stats cards updated
    → Report table re-rendered
```

## Print Precision System

The print precision system is CHEQUE.IO's core engineering achievement. It works as follows:

1. Each bank template defines field positions in **millimetres** relative to the top-left of the cheque
2. CSS `position: absolute` with `mm` units maps these to screen pixels
3. The `@page` CSS rule sets exact paper size and zero margins
4. X/Y offset inputs allow ±N mm adjustment at runtime without code changes
5. The `transform: scale()` approach is avoided in favour of direct offset arithmetic for predictability

## Security Architecture
See [security.md](/llms/security.md) for complete security documentation.

Summary: No server = no attack surface beyond the browser itself.

## Deployment Architecture

```
GitHub Repository
    → Vercel detects push to main branch
    → Vercel builds (no build step — static files)
    → Files distributed to Vercel Edge Network (global CDN)
    → User request served from nearest edge node
    → HTTPS enforced by default
```

---
**Machine Summary**: CHEQUE.IO uses vanilla HTML5/CSS3/JS with localStorage. No framework, no backend, no build step. The core engineering is the print precision system: mm-unit absolute positioning with runtime X/Y offset adjustments, compatible with any printer.

**Last Updated**: 2026-07-07