hexdev/malenia-frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
malenia-frontend/AGENTS.md
hexdev 265b1202ad v0.0.01b
2026-08-10 12:01:03 +07:00

19 KiB
Raw Permalink Blame History

MaleniaVPN — Frontend Agent Guidance

Project Overview

MaleniaVPN (malenia) is a VPN purchase service built around a pay-for-device model: one flat rate per device ("seat"), no tiers. The frontend is a Russian-language web app living in frontend/ on top of a FastAPI backend. This file is the canonical guidance for AI assistants working on it.

The service is run by a two-person studio. The brand is minimalist and archival (cream/ink/gold, extreme whitespace), but the voice is honest, ironic and sometimes snarky. Keep the UI elegant; keep the copy human.

Screens

Screen Route Access Source of truth
Landing / Public .ref/landing.html (existing hosted page)
Plan calculator /plan Public (auth needed only to confirm an order) .ref/calculator.html
Login / Signup /login Public .ref/login.html
Account /account Protected (auth required) .ref/account.html

Authoritative Source Directories (read-only)

Never edit these; they are reference material.

Path What it is
.info/openapi.json The backend API contract. All types below mirror it.
.info/ToV.md Company values and tone of voice (Russian).
.design/DESIGN.md, .design/brand.json Visual identity: palette, typography, layout posture.
.design/fonts/ Self-hosted .woff2 + fonts.css. Latin-only subsets — see Typography.
.design/logos/ favicon-0.ico — the favicon.
.ref/*.html Ready-made page references: full markup, styles and behaviors. Refactor into React, do not copy verbatim.

The .design/system/ folder (tokens, kit.html, artifacts) is brand-system material; at page build time use the canonical tokens below rather than the --brand-* derived tokens.

Tech Stack

  • Vite + React 19 + TypeScript ("strict": true)
  • React Router v6
  • Zustand — auth tokens and UI state only, never server-fetched data
  • Native fetch API client (no axios)
  • Vanilla CSS with custom properties (no Tailwind, no CSS-in-JS, no CSS frameworks)
  • Vitest + React Testing Library for tests
  • ESLint (typescript/react/hooks) + Prettier (print width 100, single quotes, trailing commas, semicolons)

Design System

Canonical CSS tokens (src/styles/tokens.css)

Token Value Usage
--bg #faf7f2 Page background (cream)
--surface #f5f0e8 Cards, raised blocks (warm white)
--fg #1a1610 Primary text, primary buttons (ink)
--muted #3d3428 Secondary text (ink-soft)
--fg-muted #7a6e5f Tertiary text, captions (ink-muted)
--accent #c9a84c Highlights, active states, emblems (gold)
--accent-light #e8ca7a Hover glow, gold-light
--accent-dim #8b6914 Emphasis inside quote text
--hairline rgba(26, 22, 16, 0.10) Faint structural rules, grid gaps
--hairline-strong rgba(26, 22, 16, 0.18) Input underlines, card borders
--border rgba(201, 168, 76, 0.25) Landing header/footer rules
--font-display 'Cormorant Garamond', Georgia, serif Headings, numerals
--font-body 'Tenor Sans', 'Helvetica Neue', Arial, sans-serif Body, labels, buttons
--radius 8px All corners
--baseline 8px Spacing unit

Layout rules

  • 8px baseline grid for spacing and padding; generous padding everywhere.
  • Extreme whitespace + centered alignment. One primary purpose per screen.
  • 1px hairlines for structural division (horizontal rules, stat strips divided by grid gap: 1px over a hairline background).
  • Buttons: uppercase, letterspacing 0.16–0.22em, 10px font-size, --radius corners. Primary = --fg background / --bg text; hover → --accent. Secondary = transparent, 1px solid var(--hairline-strong).
  • Inputs: underline style (border-bottom: 1px solid var(--hairline-strong)), transparent background, gold animated focus line (scaleX), no boxed inputs.

Signature UI details (all screens)

  • Custom cursor: gold dot (6px) + trailing ring (32px) that grows to 48px over interactive elements. Hide on touch devices (@media (hover: none), (pointer: coarse)) — these also need * { cursor: auto !important; }.
  • Grain overlay: fixed body::before with the fractal-noise SVG data-URI, opacity: 0.035, mix-blend-mode: multiply.
  • Fade-up reveals: .reveal { opacity: 0; transform: translateY(14px); } → .is-in; staggered transition-delay via IntersectionObserver.
  • Logo: Mal<span class="e">e</span>nia — Cormorant Garamond, uppercase, letter-spacing: 0.35em; the e is var(--accent).
  • Emblem: the 90×90 geometric SVG (ring + diamond + cardinal marks), gold stroke.
  • Respect prefers-reduced-motion: disable cursor animation, grain is fine (static), use plain opacity transitions without translate.

Typography

  • Display/headings: Cormorant Garamond (weights 400, 500, 600 + italics). Large sizes with line-height 1.1–1.25 and slight negative letter-spacing.
  • Body: Tenor Sans.
  • CRITICAL — Cyrillic fonts: the self-hosted .design/fonts/*.woff2 subsets have unicode-range for Latin Extended only (no U+0400–04FF) and will render Russian text with fallback glyphs. The interface is Russian, so load fonts from Google Fonts exactly as the .ref pages do: https://fonts.googleapis.com/css2?family=Cormorant+Garamond:wght@400;500;600&family=Tenor+Sans&display=swap (with preconnect links). Self-hosting is only acceptable after adding Cyrillic subsets.

Brand Voice & Copy (from .info/ToV.md)

  • All interface copy is Russian. No placeholders left in English.
  • Tone: restrained, archival and minimal on the surface; honest, ironic, occasionally snarky underneath. Plain wording, no corporate clichés, no hype ("revolutionize", "unleash the power", "best-in-class" are banned).
  • Service attitude: "включил и забыл" (set-and-forget), transparency about incidents, engineering-first, anti-censorship.
  • Tagline: «Свобода. Практика. Простота.»
  • Landing quote block: rotate randomly through the Russian quotes array from .ref/landing.html; render the second line as an italic <em>.

Routing (src/App.tsx)

Path Element Notes
/ Landing Existing marketing page
/login LoginPage Credentials only. ?returnTo= preserved for post-auth redirect
/plan PlanPage Calculator + confirm → checkout
/account AccountPage Protected: redirect to /login when unauthenticated

Backend API (mirrors .info/openapi.json — the only source of truth)

Base: backend routes have no /api/ prefix. In dev, vite.config.ts proxies /auth, /plans, /orders, /users, /payments to http://127.0.0.1:8000. In prod the reverse proxy serves same-origin. Never hardcode absolute URLs.

Types (src/types.ts)

type Provider = 'credentials' | 'telegram' | 'api';

interface UserInfo {
  username: string | null;
  telegram_id: string | null;
  referal_code: string;
}

interface LoginResponse {          // POST /auth/login
  access_token: string;
  refresh_token: string;
  expires_at: number;              // epoch seconds
  user: UserInfo;
}

interface Tokens {                 // POST /auth/refresh
  access_token: string;
  refresh_token: string;
  expires_at: number;
}

interface AddonData {              // inside GET /plans/
  id: string;
  name: string;
  price: number;
  free_threshold: number;
}

interface PricingPlans {           // GET /plans/
  device_price: number;
  addons: AddonData[];
}

interface OrderDetails {           // POST /orders/checkout body
  devices: number;
  addons: string[];                // addon ids
  duration_days: number;
}

interface CheckoutResponse {       // POST /orders/checkout → 201
  order_id: string;
  total_amount: number;
  bonus_paid: number;
  amount_to_pay: number;
  payment_link: string | null;
}

interface Device {                 // GET /users/subscription/hwid
  os: string | null;
  model: string | null;
  client: string | null;
  hwid: string;
}

Endpoint table

Method Path Auth Purpose
POST /auth/signup – Register, body {provider, username?, password?, telegram_id?, referal_code?}
POST /auth/login – Login, body {provider:'credentials', username, password}
POST /auth/refresh?refresh_token=&iss= – New token pair; iss is the provider
GET /plans/ – Pricing: device_price + addons
POST /orders/checkout yes Create order → payment_link
GET /users/me yes UserInfo
GET /users/subscription yes Subscription state (schema is {} — shape to be confirmed at implementation)
GET /users/subscription/hwid yes Device[]
DELETE /users/subscription/hwid?hwid= yes Unlink a device
POST /payments/pally/result – Payment callback — backend-internal, frontend never calls it

Auth flow

  • Credentials only. Sign up / sign in are username + password. Telegram auth is explicitly out of scope for now (linking ships later). The API accepts provider: telegram, but the frontend must only use credentials.
  • Tokens stored via a useLocalStorage-style hook under keys malenia.access, malenia.refresh, malenia.expires_at (epoch seconds).
  • The API client injects Authorization: Bearer <access> on every request.
  • On 401: try POST /auth/refresh?refresh_token=…&iss=credentials once; on success retry the original request, on failure clear tokens and redirect to /login. Guard against refresh loops.
  • Signup may include referal_code — expose an optional field on the signup form and pass it through.

API client conventions

  • Generic request<T>() helper; throws Error with the backend detail for non-2xx.
  • 201 responses return parsed JSON; no 204s in this API.
  • Errors surface as toast notifications (inline errors only for form validation).

Pages — implementation notes (from .ref/)

Landing (/) — .ref/landing.html

Keep the overall structure and design. Apply the existing page's corrections:

  • Header gains navigation links (<nav>): e.g. «Оформить» → /plan, «Канал» → https://t.me/maleniavpn (external), «Поддержка» → https://t.me/maleniasupportbot (external). Logo links to /. Keep the hairline rule + tagline layout.
  • CTA buttons (hero): primary «Оформить» → /plan; secondary «Канал» → Telegram channel (external link, keep the Telegram icon). Support link may live in the header/footer.
  • Keep: emblem, rotating quote block, divider-diamond, footer, fade-up sequence.
  • This is the existing hosted page — preserve its copy and content, only wire the corrected navigation/CTAs.

Login / Signup (/login) — .ref/login.html

  • Single page with sign-in and sign-up modes (toggle), or cleanly split states.
  • No Telegram button and no "Forgot password?" link (no such endpoint exists; credentials-only auth). Remove the ghost-telegram affordance entirely.
  • Sign-in: provider: 'credentials', username, password, show/hide password toggle, "remember" checkbox (drives refresh persistence).
  • Sign-up: username, password, optional referal_code.
  • On success → /account (or returnTo). Show auth errors via the page's status line plus toast.

Plan calculator (/plan) — .ref/calculator.html

Keep the visual language: readout, rhombus device slider (range 3–12, drag + keyboard + pointer capture), ticks, duration grid, breakdown, addon list, CTA. Rewrite the pricing logic — the .ref has known bugs and placeholder numbers.

Rewritten pricing (authoritative)

  1. Load pricing from GET /plans/ on mount (usePlans hook). Do not hardcode.
  2. Device cost is linear: deviceCost = device_price * devices. No per-seat declining curves, no volume multipliers.
  3. Addon cost is the sum of selected addons' price.
  4. Duration: options are 1 / 3 / 6 / 12 months mapped to duration_days as 30 / 90 / 180 / 365. The .ref discount multipliers (mult 0.95/0.90/0.80) are design-only placeholders — the backend data has no discount field, so do not invent one. If a "выгода" badge is shown, it must be derived from real backend data only; otherwise drop it.
  5. free_threshold on an addon: present in the backend model with unspecified semantics — ask the backend owner before wiring any rule. Until confirmed, render addons at their flat price and do not guess.
  6. Total display = deviceCost + addonCost. Show the monthly and the full-order amount (total * months) in the breakdown.

Bug notes (do not reproduce)

  • .ref referenced DOM nodes (#bd-total, #bd-period-row) that were missing from the HTML, crashing render() for multi-month durations.
  • Pricing priceFor() declining per-seat curve contradicts backend device_price.
  • The addons array was a hardcoded placeholder.

Checkout flow

  • CTA «Оформить» → if no token, redirect to /login?returnTo=/plan (preserve the chosen config in state/URL). If authed → POST /orders/checkout { devices, addons, duration_days }.
  • On 201: redirect the user to payment_link (when non-null) in the same tab; fall back to a "order created" confirmation state showing order_id / amount_to_pay when the link is null.
  • Show amount_to_pay prominently since bonus_paid may reduce it below total_amount.

Account (/account) — .ref/account.html

  • Hero: «Ваш аккаунт» + username (Cormorant, serif), sub-line from subscription data.
  • Stat strip (4 columns, gap: 1px hairline grid; 2 cols tablet, 1 col mobile): Username, Telegram ID (@… or empty state), Devices linked (n / limit), Renews / subscription expiry. Data from GET /users/me + GET /users/subscription.
  • Devices grid from GET /users/subscription/hwid. Card: OS glyph (monoline SVGs — macos/ios/android/windows/linux from .ref), model, tags (OS label · client · joined), delete button.
  • Delete flow: confirmation modal («Удалить это устройство?», shows device model), then DELETE /users/subscription/hwid?hwid=…, toast on success, grid re-rendered. Empty state: «Нет подключённых устройств» + instructions.
  • Sign out in the footer: clear tokens → /.
  • Toast: fixed bottom-center, --fg background, --bg text, auto-dismiss ~2.2s.

State Management (Zustand)

Store shape {
  auth: {
    access: string | null;
    refresh: string | null;
    expiresAt: number | null;
    user: UserInfo | null;
    setSession(tokens, user), updateUser(user), clear();
  }
}
  • Server data (plans, devices, subscription) is fetched in hooks inside components — never stored in the store.
  • Persist tokens to localStorage; hydrate on boot; empty store = unauthenticated.

Project Structure

frontend/
├── AGENTS.md
├── .design/  .info/  .ref/       # read-only reference
├── index.html                      # mount + Google Fonts links + favicon
├── public/
│   ├── favicon.ico                 # from .design/logos/favicon-0.ico
│   └── fonts/                      # optional self-hosted (latin-only — see above)
├── src/
│   ├── main.tsx
│   ├── App.tsx                     # Router, auth guard
│   ├── types.ts                    # mirrors openapi (above)
│   ├── api/client.ts               # fetch wrapper + token injection + refresh
│   ├── hooks/
│   │   ├── useLocalStorage.ts
│   │   ├── useAuth.ts
│   │   ├── usePlans.ts
│   │   └── useDevices.ts
│   ├── store/useStore.ts
│   ├── lib/format.ts               # money/pluralization helpers
│   ├── components/
│   │   ├── Cursor.tsx              # dot + ring
│   │   ├── Emblem.tsx / Logo.tsx
│   │   ├── Reveal.tsx
│   │   ├── TopBar.tsx              # landing header w/ nav + CTA links
│   │   ├── Shell.tsx               # app topbar + content (plan/account)
│   │   ├── DeviceSlider.tsx
│   │   ├── DurationSelect.tsx
│   │   ├── AddonList.tsx
│   │   ├── Breakdown.tsx
│   │   ├── StatStrip.tsx
│   │   ├── DeviceCard.tsx
│   │   ├── Modal.tsx / Toast.tsx
│   │   └── Skeleton.tsx
│   ├── pages/
│   │   ├── Landing.tsx
│   │   ├── LoginPage.tsx
│   │   ├── PlanPage.tsx
│   │   └── AccountPage.tsx
│   └── styles/
│       ├── tokens.css              # canonical tokens (table above)
│       ├── base.css                # reset, grain overlay, cursor, reveal
│       ├── components.css
│       └── pages.css

Conventions

  • TypeScript strict; all props/state/responses explicitly typed; no any; narrow with type guards from unknown.
  • No business logic in components — extract pricing/formatting into lib/ or hooks.
  • Form submit buttons show a disabled "Сохранение…" state while pending.
  • Loading → <Skeleton /> matching the content shape.
  • Errors → toast (auto-dismiss ~4s). Critical auth errors redirect to /login.
  • Semantics: <nav>, <main>, <section>, <article>, aria-label on the slider and icon-only buttons; keyboard support already in .ref (arrows/Home/End, Escape closes modal).
  • Interface copy must be in Russian (see Voice above).

Testing (Vitest + React Testing Library)

  • api/client.ts — request construction, auth header, refresh-on-401, error mapping.
  • Pricing logic (lib) — device × price, addon sums, duration→days mapping, totals.
  • LoginPage — sign-in/sign-up submit + validation, redirect after auth.
  • PlanPage — slider/duration/addon state, checkout payload, payment_link redirect.
  • AccountPage — device render, empty state, delete → confirm modal → DELETE call → toast.
  • Mock at the api/client.ts level, not per-call.

Anti-Patterns

  • No server-fetched data in Zustand. No business logic in components/routers.
  • No Tailwind/Bootstrap/CSS frameworks. No inline <style> in React components.
  • No hardcoded prices, no per-seat discount curves, no invented promo multipliers.
  • No English UI strings left in the app.
  • Don't edit .design/, .info/, .ref/ — reference only.
  • Don't call /payments/pally/result from the frontend.

Key Files Reference

File Purpose
AGENTS.md This file
.info/openapi.json Backend API contract
.info/ToV.md Voice & tone
.design/DESIGN.md, brand.json Brand identity
.ref/landing.html Landing page reference + quotes
.ref/login.html Auth page reference
.ref/calculator.html Plan/calculator reference (pricing logic is buggy — rewrite per above)
.ref/account.html Account page reference
src/api/client.ts Central API client
src/types.ts Backend-mirroring types
src/styles/tokens.css Design tokens
Reference in New Issue View Git Blame Copy Permalink