docs: Telegram Mini App pass 2 — shop/cart/account parity + frontend arch (v2.8.59)
- 04 - Flows/Telegram Mini App.md: major expansion — TelegramSellerShopView, TelegramCartView, TelegramAccountView, useTelegramCart/useTelegramShops hooks, full nav model, SDK surface table, shop→cart→checkout handoff flow - 01 - Architecture/Frontend Architecture.md: add Telegram Mini App section, TON Connect dependency, update to v2.8.59 - 09 - Audits/Activity Log.md: new entry for frontend@9bafbbb (v2.8.57–2.8.59) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Siavash Sameni
@@ -2,14 +2,15 @@
|
||||
title: Frontend Architecture
|
||||
tags: [architecture, frontend, nextjs]
|
||||
created: 2026-05-23
|
||||
updated: 2026-06-03
|
||||
---
|
||||
|
||||
|
||||
# Frontend Architecture
|
||||
|
||||
Module-level architecture of the Next.js 16 (App Router) + TypeScript + MUI v7 frontend. The current integration worktree observed locally is on `integrate-main-into-development`.
|
||||
Module-level architecture of the Next.js 16 (App Router) + TypeScript + MUI v9 frontend. The current integration worktree observed locally is on `integrate-main-into-development`.
|
||||
|
||||
> [!info]
|
||||
> Repo: `git@git.manko.yoga:222/nick/frontend.git` · Active integration branch observed locally: `integrate-main-into-development` · Version: 2.7.19 (`package.json`) · Dev port `3000`, Docker port `8083`.
|
||||
> Repo: `git@git.manko.yoga:222/nick/frontend.git` · Active integration branch observed locally: `integrate-main-into-development` · Version: 2.8.59 (`package.json`) · Dev port `3000`, Docker port `8083`.
|
||||
|
||||
---
|
||||
|
||||
@@ -36,12 +37,17 @@ frontend/src/
|
||||
│ │ ├── post/ # Admin blog editor
|
||||
│ │ ├── shop-settings/ # Seller shop config
|
||||
│ │ └── shops/ # Browse / checkout (dashboard scope)
|
||||
│ ├── telegram/ # Telegram Mini App shell (see §19)
|
||||
│ │ ├── layout.tsx # TMA root — TonConnectUIProvider + minimal providers
|
||||
│ │ ├── shop/ # Seller list + product browsing
|
||||
│ │ ├── cart/ # In-shell cart + checkout handoff
|
||||
│ │ └── account/ # Account tab (dashboard parity)
|
||||
│ ├── error/ # Global error page
|
||||
│ └── not-found.tsx # 404
|
||||
├── sections/ # Page-specific composition modules (one folder per feature)
|
||||
│ └── (chat|payment|request|request-template|dispute|user|points|...)
|
||||
│ └── (chat|payment|request|request-template|dispute|user|points|telegram|...)
|
||||
├── components/ # Reusable UI primitives (hook-form, table, upload, editor, ...)
|
||||
├── layouts/ # Page-template wrappers (auth-centered, auth-split, dashboard, main)
|
||||
├── layouts/ # Page-template wrappers (auth-centered, auth-split, dashboard, main, telegram)
|
||||
├── theme/ # MUI theme creation, palette, typography, overrides
|
||||
├── settings/ # Settings drawer (mode, layout, direction, color, font)
|
||||
├── contexts/ # React Context providers (socket-context)
|
||||
@@ -80,6 +86,8 @@ flowchart TB
|
||||
|
||||
Order matters: theme must wrap query (because mutations show snackbars styled by theme); socket wraps snackbar (so socket-driven notifications can fire snackbars).
|
||||
|
||||
The Telegram Mini App shell (`app/telegram/`) uses its own slimmer layout that replaces the dashboard shell with `TonConnectUIProvider` and skips the settings drawer (see §19).
|
||||
|
||||
---
|
||||
|
||||
## 4. Route layout & guards
|
||||
@@ -92,8 +100,9 @@ Order matters: theme must wrap query (because mutations show snackbars styled by
|
||||
| `dashboard/user/*` | dashboard | + `role: admin` |
|
||||
| `dashboard/post/*` (editor) | dashboard | + `role: admin` |
|
||||
| `dashboard/shop-settings/*` | dashboard | + `role: seller` |
|
||||
| `telegram/*` | `layouts/telegram` (bottom-tab shell) | Telegram `initData` token guard + role check |
|
||||
|
||||
Guards live in `frontend/src/auth/` (HOC + hook). They consult the JWT-derived user context and redirect unauthenticated to `/auth/jwt/sign-in?returnTo=...`.
|
||||
Guards live in `frontend/src/auth/` (HOC + hook). They consult the JWT-derived user context and redirect unauthenticated to `/auth/jwt/sign-in?returnTo=...`. The Telegram guard additionally validates `window.Telegram.WebApp.initData` before issuing a session.
|
||||
|
||||
---
|
||||
|
||||
@@ -189,6 +198,8 @@ Higher-level hooks build on this:
|
||||
| `use-marketplace-socket` | broad market events |
|
||||
| `use-unified-real-time` | multi-event aggregator |
|
||||
|
||||
The Telegram Mini App shell reuses the same `SocketProvider` — live socket updates are available in the TMA shop, cart, and account tabs.
|
||||
|
||||
See [[Real-time Layer]] for the full event catalog.
|
||||
|
||||
---
|
||||
@@ -213,6 +224,8 @@ const config = createConfig({
|
||||
|
||||
Wallet UI: connect / disconnect / show address / show balance via `use-web3-wagmi`, `use-web3-context`. The current checkout target is the Request Network in-house flow; the DePay widget package remains legacy/frontier context and should not be treated as the primary path.
|
||||
|
||||
TON wallet support is handled separately via `@ton/core` + `@tonconnect/ui-react` in the Telegram Mini App layer (see §19).
|
||||
|
||||
---
|
||||
|
||||
## 10. Internationalization
|
||||
@@ -288,6 +301,9 @@ See [[Theme Configuration]] and [[Design System Overview]].
|
||||
|
||||
State persists in `localStorage` under `settings-key`.
|
||||
|
||||
> [!note]
|
||||
> The Telegram Mini App shell does not render the settings drawer; theme and direction are inherited from the parent app's stored settings at launch.
|
||||
|
||||
---
|
||||
|
||||
## 14. Editor (TipTap)
|
||||
@@ -350,6 +366,7 @@ See [[Docker Setup]], [[CI-CD Pipeline]], and [[Deployment]].
|
||||
| File | Why it matters |
|
||||
|---|---|
|
||||
| `src/app/layout.tsx` | Provider tree |
|
||||
| `src/app/telegram/layout.tsx` | TMA shell — TonConnectUIProvider + slim provider tree |
|
||||
| `src/lib/axios.ts` | Every HTTP call goes through this |
|
||||
| `src/contexts/socket-context.tsx` | Realtime plumbing |
|
||||
| `src/theme/index.ts` | Theme creation entry |
|
||||
@@ -359,6 +376,67 @@ See [[Docker Setup]], [[CI-CD Pipeline]], and [[Deployment]].
|
||||
|
||||
---
|
||||
|
||||
## 19. Telegram Mini App (TMA) layer
|
||||
|
||||
### Overview
|
||||
|
||||
The app ships a dedicated Telegram Mini App shell at `app/telegram/`. It is served from the same Next.js process and Docker image as the main web app; no separate deployment is required. The Telegram bot registers the Mini App URL pointing at `/telegram`.
|
||||
|
||||
### Provider tree (TMA layout)
|
||||
|
||||
The TMA layout replaces the full dashboard shell with a minimal provider stack:
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
A[TelegramLayout]
|
||||
A --> B[AppRouterCacheProvider]
|
||||
B --> C[ThemeProvider]
|
||||
C --> D[QueryClientProvider]
|
||||
D --> E[SocketProvider]
|
||||
E --> F[TonConnectUIProvider<br/>manifestUrl: /tonconnect-manifest.json]
|
||||
F --> G[SnackbarProvider]
|
||||
G --> H[Children — telegram routes]
|
||||
```
|
||||
|
||||
`TonConnectUIProvider` is the only addition relative to the web tree. Settings drawer, i18n provider, and auth guards are replaced by a Telegram `initData` token guard.
|
||||
|
||||
### Routes and features
|
||||
|
||||
| Route | Description |
|
||||
|---|---|
|
||||
| `telegram/shop` | Seller list with product browsing; infinite scroll |
|
||||
| `telegram/shop/[seller]` | Single seller's catalogue |
|
||||
| `telegram/cart` | In-shell shopping cart; checkout hands off to full web checkout URL |
|
||||
| `telegram/account` | Account tab with dashboard parity: profile, wallet, order history |
|
||||
|
||||
### Authentication flow
|
||||
|
||||
1. Telegram injects `window.Telegram.WebApp.initData` on launch.
|
||||
2. The TMA guard sends `initData` to `/api/auth/telegram` for HMAC verification.
|
||||
3. On success the backend issues a short-lived JWT that the axios instance attaches as `Bearer`.
|
||||
4. Role-based access (seller vs buyer views) is honoured via the same guard mechanism used in the dashboard.
|
||||
|
||||
### Real-time
|
||||
|
||||
`SocketProvider` is reused unchanged. The TMA shop, cart, and account tabs receive live socket updates (new messages, payment status, cart changes) on the same room infrastructure as the web dashboard.
|
||||
|
||||
### TON Connect (Telegram Wallet)
|
||||
|
||||
**Dependencies added**: `@ton/core`, `@tonconnect/ui-react`.
|
||||
|
||||
`TonConnectUIProvider` wraps the TMA routes and exposes a `useTonConnectUI()` hook. The manifest at `public/tonconnect-manifest.json` declares the app identity to the TON Connect protocol.
|
||||
|
||||
Current status: the wallet connection UI is in place (connect / disconnect / show address). **Actual TON payment processing is not yet wired to the backend** — the provider is pre-positioned for a future TON payment rail on the escrow platform. When that rail is built, the checkout handoff in `telegram/cart` will be extended to emit a TON transaction instead of redirecting to the web checkout.
|
||||
|
||||
### Constraints and differences from web
|
||||
|
||||
- No settings drawer (theme follows web localStorage, defaults to light/ltr).
|
||||
- No TipTap editor or file-upload dropzone in TMA routes.
|
||||
- `@mui/x-date-pickers` and DataGrid are not loaded in the TMA bundle.
|
||||
- COOP/COEP headers required for WalletConnect popups are relaxed for TMA routes because Telegram's WebView does not support `SharedArrayBuffer`.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [[System Architecture]] — bird's-eye topology
|
||||
|
||||
Reference in New Issue
Block a user