Architecture and Tech Stack

Architecture and Tech Stack

Zefer is a client-heavy Next.js application. All cryptography runs in the browser; the only server-side piece is a small cached endpoint for the project page.

Tech stack

• Next.js 16.2.7 (App Router) with React 19
• TypeScript 6
• Tailwind CSS v4 (design tokens via CSS variables)
• Web Crypto API (AES-256-GCM, PBKDF2-SHA256) and CompressionStream API
• Lucide React icons, Sonner toasts
• Vitest + @vitest/coverage-v8 — 161 tests, 100% line coverage

Routes

Route	Type	Indexable	Purpose
/	Static	Yes	Home — encrypt/decrypt tabs
/how	Static	Yes	How it works + specs + channels
/generator	Static	Yes	Password generator + analyzer
/analyzer	Static	Yes	.zefer file inspector
/mcp	Static	Yes	zefer-cli as an MCP server
/library	Static	Yes	zefer-cli as a Node.js library
/project	Static	Yes	Project, stack, creator, donate
/device	Static	Yes	Device detection + optimization
/install	Static	Yes	Install / self-host / PWA
/install/guide	Static	Yes	Step-by-step usage guide
/privacy /terms /security /conduct	Static	No (noindex, follow)	Legal & policy
/vs/hat-sh /vs/picocrypt /vs/bitwarden-send /vs/cryptomator /vs/veracrypt	Static	Yes	Comparisons
/api/author	Dynamic	—	Cached GitHub profile (1h TTL)
/llms.txt	Static	Yes	LLM context file

Project structure

app/
  api/author/route.ts     GitHub profile cache (1h TTL)
  components/             client components (forms, content, UI)
  lib/
    crypto.ts             AES-256-GCM, PBKDF2, benchmark, dual key
    zefer.ts              ZEFB3/ZEFR3 encode/decode + all security checks
    chunked-crypto.ts     16 MB chunked encryption (unique IVs)
    compression.ts        Gzip/Deflate via CompressionStream
    device.ts             RAM/CPU/GPU detection, dynamic file limits
    i18n.ts               translations (es/en/pt)
    ip.ts                 IP detection + allowlist check
    passwords.ts          charsets, unbiased keygen, entropy/analysis
    preferences.ts        persisted user preferences
    seo.ts                centralized page metadata helper
  globals.css             design system (liquid glass, 2 themes)
docs/                     Architecture, Security, Deployment, Contributing
public/
  llms.txt                LLM context file

Client-side rendering & SEO

Pages are server-rendered so that full content, a real <h1>, and per-page JSON-LD ship in the static HTML — important for search engines and non-JS AI crawlers. Metadata is centralized in app/lib/seo.ts (pageMetadata()), which guarantees every route exposes a complete, consistent Open Graph + Twitter set, canonical URL, and robots directive. JSON-LD includes WebApplication, BreadcrumbList, FAQPage, and WebSite schemas where relevant.

Theming

Two themes ([data-theme="dark"] / light) driven entirely by CSS variables — components never hardcode colors. A text hierarchy (theme-heading → theme-text → theme-muted → theme-faint), liquid-glass surfaces (glass, glass-nav), and the brand green (--primary: #22c55e) with a green→cyan gradient accent. The theme toggle uses the View Transitions API for a circular reveal. Everything respects prefers-reduced-motion.

Device-aware limits

lib/device.ts detects RAM, CPU threads, and GPU to compute a dynamic maximum file size (the /device page shows your machine's analysis). High-end workstations can encrypt multi-gigabyte files; low-memory devices are capped conservatively to avoid out-of-memory failures.

Testing

161 Vitest tests across the crypto, format, password, compression, and IP modules; 100% statement/function/line coverage, ~99% branch. Run npm test (single run) or npm run test:watch.

See Contributing for development setup and conventions.

---

📖 Glossary — terms on this page: client-side · Web Crypto API · AES-256-GCM · PBKDF2 · chunk · public header. Full list in the Glossary.