# nitinkokane3/samplecalc architecture

> Architecture diagram of the GitHub repository nitinkokane3/samplecalc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nitinkokane3/samplecalc
- Repository: https://github.com/nitinkokane3/samplecalc

## Overview

#### Purpose and Delivery Model
This repository is a browser-based advanced calculator supporting multiple mathematical and financial modes. It is deliberately framework-free: the application is delivered as static HTML, CSS, and JavaScript, with no compilation or server-side runtime. Primary launch points are `index.html`, `script.js`, and `style.css`.

#### Application Shell and UI
`index.html` defines the calculator shell, controls, mode-specific panels, dialogs, and accessibility-facing markup. `style.css` provides the responsive layout and visual states. `script.js` owns client-side behavior, including mode switching, input handling, display updates, and UI state transitions.

Key paths:
- `index.html`
- `script.js`
- `style.css`

#### Calculation Mode Engine
The central application logic is consolidated in `script.js`, which implements the distinct calculator domains: standard/scientific arithmetic, programmer operations, unit conversion, statistics, equation solving, graphing, matrices, vectors, complex numbers, regression, and finance. This makes the script both the shared interaction controller and the boundary between UI events and domain calculations.

Key path:
- `script.js`

#### Stateful Client-Side Features
All calculation state, histories, saved data, and mode-specific working values are browser-resident. The app has no indicated backend or database dependency. Backup/restore, localization, accessibility, security/CSP behavior, responsive operation, and offline behavior are material product concerns, reflected by dedicated end-to-end coverage.

Key paths:
- `script.js`
- `tests/specs/backup.spec.js`
- `tests/specs/i18n.spec.js`

#### PWA and Offline Boundary
The application is installable and supports offline use after an initial network visit. `manifest.json` supplies install metadata, while `sw.js` is the service-worker boundary responsible for caching static application assets and serving them offline.

Key paths:
- `manifest.json`
- `sw.js`
- `index.html`

#### Documentation and User-Facing Reference
The repository includes a standalone browser-readable manual with screenshots and examples. It is separate from the runtime app but documents the calculator’s mode model and expected workflows.

Key paths:
- `README.md`
- `docs/user-manual.html`
- `docs/manual-images`

#### Validation and Deployment
Browser-level tests use Playwright against a local static server. `tests/run.js` coordinates server startup and headless Chromium execution; individual specs validate modes and cross-cutting behaviors. GitHub Actions runs tests and deploys the static site to Pages.

Key paths:
- `tests/run.js`
- `tests/server.js`
- `.github/workflows/test.yml`
- `.github/workflows/deploy-pages.yml`

Main entry points: [`index.html`](https://github.com/nitinkokane3/samplecalc/blob/main/index.html) (Calculator shell), [`script.js`](https://github.com/nitinkokane3/samplecalc/blob/main/script.js) (UI controller), [`tests/run.js`](https://github.com/nitinkokane3/samplecalc/blob/main/tests/run.js) (Browser test runner), [`sw.js`](https://github.com/nitinkokane3/samplecalc/blob/main/sw.js) (Offline cache worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Browser Application"]
  node_shell["Calculator shell<br/>HTML entry<br/>[index.html]"]
  node_styles["Responsive styling<br/>CSS<br/>[style.css]"]
  node_controller["UI controller<br/>client logic<br/>[script.js]"]
  node_mode_engine["Calculation modes<br/>domain engine<br/>[script.js]"]
  node_client_state[("Browser state &amp; history<br/>client storage<br/>[script.js]")]
end

subgraph group_offline["PWA &amp; Offline"]
  node_manifest["Install manifest<br/>PWA metadata<br/>[manifest.json]"]
  node_service_worker{{"Offline cache worker<br/>service worker<br/>[sw.js]"}}
end

subgraph group_docs["Documentation"]
  node_readme["Project reference<br/>README<br/>[README.md]"]
  node_manual["User manual<br/>HTML manual<br/>[user-manual.html]"]
  node_manual_images["Manual screenshots<br/>image assets"]
end

subgraph group_quality["Validation &amp; Delivery"]
  node_test_runner["Browser test runner<br/>test orchestration<br/>[run.js]"]
  node_test_server["Local static server<br/>test server<br/>[server.js]"]
  node_backup_specs["Backup tests<br/>Playwright specs<br/>[backup.spec.js]"]
  node_i18n_specs["Localization tests<br/>Playwright specs<br/>[i18n.spec.js]"]
  node_test_ci{{"Test workflow<br/>GitHub Actions<br/>[test.yml]"}}
  node_deploy_ci{{"Pages deployment<br/>GitHub Actions<br/>[deploy-pages.yml]"}}
end

node_shell -->|"loads"| node_styles
node_shell -->|"loads"| node_controller
node_controller -->|"dispatches calculations"| node_mode_engine
node_controller -->|"reads and updates"| node_client_state
node_mode_engine -->|"stores results"| node_client_state
node_shell -->|"declares installability"| node_manifest
node_service_worker -->|"caches and serves"| node_shell
node_service_worker -->|"caches"| node_styles
node_service_worker -->|"caches"| node_controller
node_manual -->|"uses"| node_manual_images
node_readme -.->|"references"| node_manual
node_test_runner -->|"starts"| node_test_server
node_test_runner -->|"runs"| node_backup_specs
node_test_runner -->|"runs"| node_i18n_specs
node_test_server -->|"serves"| node_shell
node_backup_specs -.->|"validates"| node_client_state
node_i18n_specs -.->|"validates"| node_controller
node_test_ci -->|"executes"| node_test_runner
node_deploy_ci -->|"publishes"| node_shell

click node_shell "https://github.com/nitinkokane3/samplecalc/blob/main/index.html"
click node_styles "https://github.com/nitinkokane3/samplecalc/blob/main/style.css"
click node_controller "https://github.com/nitinkokane3/samplecalc/blob/main/script.js"
click node_mode_engine "https://github.com/nitinkokane3/samplecalc/blob/main/script.js"
click node_client_state "https://github.com/nitinkokane3/samplecalc/blob/main/script.js"
click node_manifest "https://github.com/nitinkokane3/samplecalc/blob/main/manifest.json"
click node_service_worker "https://github.com/nitinkokane3/samplecalc/blob/main/sw.js"
click node_readme "https://github.com/nitinkokane3/samplecalc/blob/main/README.md"
click node_manual "https://github.com/nitinkokane3/samplecalc/blob/main/docs/user-manual.html"
click node_manual_images "https://github.com/nitinkokane3/samplecalc/tree/main/docs/manual-images"
click node_test_runner "https://github.com/nitinkokane3/samplecalc/blob/main/tests/run.js"
click node_test_server "https://github.com/nitinkokane3/samplecalc/blob/main/tests/server.js"
click node_backup_specs "https://github.com/nitinkokane3/samplecalc/blob/main/tests/specs/backup.spec.js"
click node_i18n_specs "https://github.com/nitinkokane3/samplecalc/blob/main/tests/specs/i18n.spec.js"
click node_test_ci "https://github.com/nitinkokane3/samplecalc/blob/main/.github/workflows/test.yml"
click node_deploy_ci "https://github.com/nitinkokane3/samplecalc/blob/main/.github/workflows/deploy-pages.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_shell,node_styles,node_controller,node_mode_engine,node_client_state toneBlue
class node_manifest,node_service_worker toneAmber
class node_readme,node_manual,node_manual_images toneMint
class node_test_runner,node_test_server,node_backup_specs,node_i18n_specs,node_test_ci,node_deploy_ci toneRose
```

## Components

### Browser Application

- [Calculator shell](https://github.com/nitinkokane3/samplecalc/blob/main/index.html): HTML entry · Defines controls, panels, dialogs, and accessibility markup. · `index.html`
- [Responsive styling](https://github.com/nitinkokane3/samplecalc/blob/main/style.css): CSS · `style.css`
- [UI controller](https://github.com/nitinkokane3/samplecalc/blob/main/script.js): client logic · Handles events, mode switching, displays, and UI transitions. · `script.js`
- [Calculation modes](https://github.com/nitinkokane3/samplecalc/blob/main/script.js): domain engine · Implements arithmetic, scientific, finance, graphing, matrices, and other modes. · `script.js`
- [Browser state & history](https://github.com/nitinkokane3/samplecalc/blob/main/script.js): client storage · Keeps calculations, saved data, and mode working values in the browser. · `script.js`

### PWA & Offline

- [Install manifest](https://github.com/nitinkokane3/samplecalc/blob/main/manifest.json): PWA metadata · `manifest.json`
- [Offline cache worker](https://github.com/nitinkokane3/samplecalc/blob/main/sw.js): service worker · Caches static assets and serves the app offline. · `sw.js`

### Documentation

- [Project reference](https://github.com/nitinkokane3/samplecalc/blob/main/README.md): README · `README.md`
- [User manual](https://github.com/nitinkokane3/samplecalc/blob/main/docs/user-manual.html): HTML manual · Browser-readable workflows, examples, and screenshots. · `docs/user-manual.html`
- [Manual screenshots](https://github.com/nitinkokane3/samplecalc/tree/main/docs/manual-images): image assets · `docs/manual-images`

### Validation & Delivery

- [Browser test runner](https://github.com/nitinkokane3/samplecalc/blob/main/tests/run.js): test orchestration · Starts the local server and runs headless Chromium tests. · `tests/run.js`
- [Local static server](https://github.com/nitinkokane3/samplecalc/blob/main/tests/server.js): test server · `tests/server.js`
- [Backup tests](https://github.com/nitinkokane3/samplecalc/blob/main/tests/specs/backup.spec.js): Playwright specs · `tests/specs/backup.spec.js`
- [Localization tests](https://github.com/nitinkokane3/samplecalc/blob/main/tests/specs/i18n.spec.js): Playwright specs · `tests/specs/i18n.spec.js`
- [Test workflow](https://github.com/nitinkokane3/samplecalc/blob/main/.github/workflows/test.yml): GitHub Actions · `.github/workflows/test.yml`
- [Pages deployment](https://github.com/nitinkokane3/samplecalc/blob/main/.github/workflows/deploy-pages.yml): GitHub Actions · Deploys the static site to GitHub Pages. · `.github/workflows/deploy-pages.yml`

## Connections

- Calculator shell → Responsive styling: loads
- Calculator shell → UI controller: loads
- UI controller → Calculation modes: dispatches calculations
- UI controller → Browser state & history: reads and updates
- Calculation modes → Browser state & history: stores results
- Calculator shell → Install manifest: declares installability
- Offline cache worker → Calculator shell: caches and serves
- Offline cache worker → Responsive styling: caches
- Offline cache worker → UI controller: caches
- User manual → Manual screenshots: uses
- Project reference → User manual: references
- Browser test runner → Local static server: starts
- Browser test runner → Backup tests: runs
- Browser test runner → Localization tests: runs
- Local static server → Calculator shell: serves
- Backup tests → Browser state & history: validates
- Localization tests → UI controller: validates
- Test workflow → Browser test runner: executes
- Pages deployment → Calculator shell: publishes