# ravish-ranjan/encode architecture

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

- Interactive diagram: https://gitdiagram.com/ravish-ranjan/encode
- Repository: https://github.com/ravish-ranjan/encode

## Overview

This is an Express QR-code generation API with a small browser-facing frontend. Clients submit typed QR data through either the backward-compatible v1 routes or the shorter v2 routes; middleware parses and validates the request, generates or retrieves a PNG, and the controller returns it. The formatter supports the documented text/URL, contact, network, messaging, location, event, Bitcoin, and UPI formats. Redis is optional for image caching and rate-limit storage. The graph follows visible route and middleware wiring; frontend-to-API calls are not asserted because the sampled evidence does not establish them.

Main entry points: [`src/app.ts`](https://github.com/ravish-ranjan/encode/blob/main/src/app.ts) (Express Application), [`src/routers/qrv1.route.ts`](https://github.com/ravish-ranjan/encode/blob/main/src/routers/qrv1.route.ts) (v1 Routes), [`src/routers/qrv2.route.ts`](https://github.com/ravish-ranjan/encode/blob/main/src/routers/qrv2.route.ts) (v2 Routes), [`src/middlewares/cache.middleware.ts`](https://github.com/ravish-ranjan/encode/blob/main/src/middlewares/cache.middleware.ts) (Image Cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_app["Express Application<br/>[app.ts]"]
  node_v1["v1 Routes<br/>[qrv1.route.ts]"]
  node_v2["v2 Routes<br/>[qrv2.route.ts]"]
  node_parser["Request Parser"]
  node_errors["Validation Errors"]
  node_renderer["PNG Response"]
end

subgraph group_generation["QR Generation"]
  node_cache["Image Cache"]
  node_formatter["Payload Formatter<br/>[qrcode.service.ts]"]
  node_qrengine["QRCode Library"]
end

subgraph group_runtime["Runtime Services"]
  node_redisconfig["Redis Client<br/>[redis.ts]"]
  node_redis[("Redis Store")]
  node_env["Environment Config<br/>[env.ts]"]
end

subgraph group_frontend["Browser Frontend"]
  node_webui["Web UI<br/>[index.html]"]
  node_webscript["UI Script<br/>[script.js]"]
end

node_client(("API Client"))
node_browser(("Browser User"))

node_client -->|"sends requests"| node_app
node_app -->|"mounts at /api"| node_v1
node_app -->|"mounts at /api/v2"| node_v2
node_v1 -->|"parses requests"| node_parser
node_v2 -->|"parses requests"| node_parser
node_parser -->|"creates errors"| node_errors
node_v1 -->|"runs middleware"| node_cache
node_v2 -->|"runs middleware"| node_cache
node_v1 -->|"returns PNG"| node_renderer
node_v2 -->|"returns PNG"| node_renderer
node_cache -->|"generates image"| node_formatter
node_formatter -->|"encodes payload"| node_qrengine
node_cache -->|"reads and writes"| node_redisconfig
node_redisconfig -.->|"connects optionally"| node_redis
node_redisconfig -->|"reads settings"| node_env
node_app -->|"uses rate-limit store"| node_redisconfig
node_app -->|"serves frontend"| node_webui
node_browser -.->|"opens interface"| node_webui

click node_app "https://github.com/ravish-ranjan/encode/blob/main/src/app.ts"
click node_v1 "https://github.com/ravish-ranjan/encode/blob/main/src/routers/qrv1.route.ts"
click node_v2 "https://github.com/ravish-ranjan/encode/blob/main/src/routers/qrv2.route.ts"
click node_parser "https://github.com/ravish-ranjan/encode/blob/main/src/middlewares/parse.middleware.ts"
click node_errors "https://github.com/ravish-ranjan/encode/blob/main/src/services/apperror.service.ts"
click node_cache "https://github.com/ravish-ranjan/encode/blob/main/src/middlewares/cache.middleware.ts"
click node_renderer "https://github.com/ravish-ranjan/encode/blob/main/src/controllers/qrcode.controller.ts"
click node_formatter "https://github.com/ravish-ranjan/encode/blob/main/src/services/qrcode.service.ts"
click node_redisconfig "https://github.com/ravish-ranjan/encode/blob/main/src/configs/redis.ts"
click node_env "https://github.com/ravish-ranjan/encode/blob/main/src/configs/env.ts"
click node_webui "https://github.com/ravish-ranjan/encode/blob/main/public/index.html"
click node_webscript "https://github.com/ravish-ranjan/encode/blob/main/public/script.js"

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_app,node_v1,node_v2,node_parser,node_errors,node_renderer,node_client,node_browser toneBlue
class node_cache,node_formatter,node_qrengine toneAmber
class node_redisconfig,node_redis,node_env toneMint
class node_webui,node_webscript toneRose
```

## Components

### HTTP API

- [Express Application](https://github.com/ravish-ranjan/encode/blob/main/src/app.ts): `src/app.ts`
- [v1 Routes](https://github.com/ravish-ranjan/encode/blob/main/src/routers/qrv1.route.ts): `src/routers/qrv1.route.ts`
- [v2 Routes](https://github.com/ravish-ranjan/encode/blob/main/src/routers/qrv2.route.ts): `src/routers/qrv2.route.ts`
- [Request Parser](https://github.com/ravish-ranjan/encode/blob/main/src/middlewares/parse.middleware.ts): `src/middlewares/parse.middleware.ts`
- [Validation Errors](https://github.com/ravish-ranjan/encode/blob/main/src/services/apperror.service.ts): `src/services/apperror.service.ts`
- [PNG Response](https://github.com/ravish-ranjan/encode/blob/main/src/controllers/qrcode.controller.ts): `src/controllers/qrcode.controller.ts`

### QR Generation

- [Image Cache](https://github.com/ravish-ranjan/encode/blob/main/src/middlewares/cache.middleware.ts): `src/middlewares/cache.middleware.ts`
- [Payload Formatter](https://github.com/ravish-ranjan/encode/blob/main/src/services/qrcode.service.ts): `src/services/qrcode.service.ts`
- **QRCode Library**

### Runtime Services

- [Redis Client](https://github.com/ravish-ranjan/encode/blob/main/src/configs/redis.ts): `src/configs/redis.ts`
- **Redis Store**
- [Environment Config](https://github.com/ravish-ranjan/encode/blob/main/src/configs/env.ts): `src/configs/env.ts`

### Browser Frontend

- [Web UI](https://github.com/ravish-ranjan/encode/blob/main/public/index.html): `public/index.html`
- [UI Script](https://github.com/ravish-ranjan/encode/blob/main/public/script.js): `public/script.js`

### Other components

- **API Client**
- **Browser User**

## Connections

- API Client → Express Application: sends requests (evidence: `README.md`)
- Express Application → v1 Routes: mounts at /api (evidence: `src/app.ts`)
- Express Application → v2 Routes: mounts at /api/v2 (evidence: `src/app.ts`)
- v1 Routes → Request Parser: parses requests (evidence: `src/routers/qrv1.route.ts`)
- v2 Routes → Request Parser: parses requests (evidence: `src/routers/qrv2.route.ts`)
- Request Parser → Validation Errors: creates errors (evidence: `src/middlewares/parse.middleware.ts`)
- v1 Routes → Image Cache: runs middleware (evidence: `src/routers/qrv1.route.ts`)
- v2 Routes → Image Cache: runs middleware (evidence: `src/routers/qrv2.route.ts`)
- v1 Routes → PNG Response: returns PNG (evidence: `src/routers/qrv1.route.ts`)
- v2 Routes → PNG Response: returns PNG (evidence: `src/routers/qrv2.route.ts`)
- Image Cache → Payload Formatter: generates image (evidence: `src/middlewares/cache.middleware.ts`)
- Payload Formatter → QRCode Library: encodes payload (evidence: `src/services/qrcode.service.ts`)
- Image Cache → Redis Client: reads and writes (evidence: `src/middlewares/cache.middleware.ts`)
- Redis Client → Redis Store: connects optionally (evidence: `src/configs/redis.ts`)
- Redis Client → Environment Config: reads settings (evidence: `src/configs/redis.ts`)
- Express Application → Redis Client: uses rate-limit store (evidence: `src/app.ts`)
- Express Application → Web UI: serves frontend (evidence: `src/app.ts`)
- Browser User → Web UI: opens interface
