# Marisana Rose Manga Arabic-first, mobile-first publishing community for manga and novels with creator studios, social reading, and a private Super Admin console. ## Masterplan - Serve Arabic-speaking manga creators, novelists, illustrators, and readers; English localizes the interface while user-published content can be in any language. - Provide durable accounts, profiles, manga/novel publishing, media uploads, reading progress, follows, likes, comments, notifications, and messages through GenMB services. - Let creators structure manga as `Work → Volume → Chapter → Pages`; novels use the same work/volume/chapter hierarchy with chapter text and optional embedded images. - Deliver elegant sakura-themed discovery, profiles, reading, creator tools, and admin-managed news, contests, winners, featured artists, announcements, branding, and seasonal themes. - Never seed or display fake statistics: dashboard and homepage statistics must derive from persistent records. ## Tech Stack & Architecture - **React 19 + TypeScript**, bootstrapped by `src/main.tsx`. - **Vite** configured in `vite.config.ts`. - **React Router DOM** using `HashRouter`. Public URLs follow hash-routing patterns such as `/#/search`; preserve this for static-host compatibility. - **Tailwind CSS v4**, with all theme tokens, glass styling, sakura animation, responsive behavior, and event themes in `src/styles/main.css`. - **Lucide React** is the only icon library. Do not add a competing icon package. - **`clsx` + `tailwind-merge`**, exposed through `cn()` in `src/lib/utils.ts`. ### Provider order Keep this exact provider nesting in `src/main.tsx`: ```tsx ``` `RbacProvider` intentionally wraps `AuthProvider`. Route authorization must remain independent from visible account-menu state. ### GenMB services and persistence `index.html` injects the GenMB SDKs and `src/types/genmb.d.ts` declares their global types. | Service | Use | |---|---| | `window.genmb.auth` | Password signup with OTP verification, password login, Google login, sessions, logout, password reset. | | `window.genmb.kv` | Durable structured records for profiles, works, chapters, interactions, notifications, admin content, and settings. | | `window.genmb.storage` | Validates and uploads media with progress reporting. | | `window.genmb.rbac` | Super Admin role checks and role clearing on logout. | | `window.genmb.audit` | Audit logging for privileged dashboard actions. | `src/lib/persistence.ts` is the only domain data-access layer. Components must call its exported functions; do **not** directly call `window.genmb.kv` from feature components. The only intentional `localStorage` use is `marisana-language` in `src/i18n.tsx`. Never store sessions, credentials, profiles, works, likes, reading progress, or messages in browser storage. ### Key persistence patterns and gotchas - Owner records use owner-scoped keys, e.g. `work:${ownerId}:${workId}`. - Published works are copied to `published-work:${id}` so public search/discovery does not require owner knowledge. Any publish/unpublish operation must update both representations via `saveWork()`. - Username login resolves `username:${normalizedUsername}` to an email with `resolveLoginIdentifier()`. - `ensureProfile()` creates a persisted profile after authentication. `src/auth.tsx` also records account visits for authenticated sessions. - `safeText()` removes `<`/`>` and truncates strings. Apply it to every newly persisted user-controlled text field. - Preserve backward-compatible record shapes in `src/lib/persistence.ts`; existing KV records may omit newly added optional fields. - Upload interfaces must use `Uploader` from `src/components/PersistentStudio.tsx`. It supports mobile file selection, multiple uploads, storage validation, progress, failure display, and retry. - The app relies on GenMB authentication/session security and RBAC. Do not expose admin passwords, role secrets, or privileged assumptions in frontend code. ## File Structure ```text index.html HTML shell, SEO metadata, React mount point, injected GenMB SDKs. package.json Vite scripts and frontend dependencies. vite.config.ts Vite build configuration. src/main.tsx Application entry point and provider composition. src/App.tsx Routes, public pages, auth flows, shell, reader, profile, search, contact. src/auth.tsx Auth context; waits for GenMB session, creates profiles, tracks visits. src/rbac.tsx RBAC context and protected Super Admin route behavior. src/i18n.tsx Arabic/English context; stores only language preference locally. src/toast.tsx Toast context and notification helpers. src/components/ui.tsx Shared accessible buttons, fields, cards, dialogs, empty/error states, toaster. src/components/PersistentStudio.tsx Creator work/volume/chapter studio and reusable real-file Uploader. src/components/AdminDashboard.tsx Private Super Admin dashboard and content/settings management. src/lib/persistence.ts Domain types, KV key conventions, durable CRUD, search, interactions, uploads. src/lib/utils.ts cn() class utility and email validation. src/locales/ar.json Default Arabic UI strings. src/locales/en.json English UI strings. src/styles/main.css Tailwind imports/tokens, sakura effects, glass surfaces, event-theme variants. src/types/genmb.d.ts Type declarations for injected GenMB services. ``` ## Key Features ### Authentication and profiles - Registration accepts username, email, password, confirmation, then completes GenMB OTP verification. - Login accepts username or email; usernames resolve to stored email mappings before password login. - Authenticated users get a durable `ProfileRecord` containing username, email, bio, avatar, role, and timestamps. - Profile updates validate username uniqueness through `isUsernameAvailable()` and maintain the `username:*` index. - Avatar uploads use `uploadAvatar()` and GenMB storage validation. ### Publishing studio `src/components/PersistentStudio.tsx` provides creator-owned work management. - Work fields follow `WorkRecord`: title, English title, summary, type (`Manga` or `Novel`), category, status, year, author, artist, language, age warning, tags, cover, banner, publishing state, optional series/related-work metadata. - A manga chapter stores ordered `PageRecord[]`. - A novel chapter stores `text` and can include `EmbeddedImage[]`. - Chapters may contain `TrackRecord[]` audio metadata, including optional page attachment and playback positions. - Volumes are optional organizational folders and use `VolumeRecord`. - Chapter/page ordering is persisted through each record’s `number` or `position`; do not rely on filename sorting. - Publishing is forbidden to anonymous users. Public discovery must only use published work/chapter/volume accessors. ### Reading and discovery `src/App.tsx` implements public discovery, search, work pages, chapter reading, and profile views. - Search uses `searchPublishedWorks()` against durable published records. - Manga reader supports vertical reading, zoom controls, fullscreen behavior, light/dark reader treatment, chapter navigation, and persisted reading progress. - `saveProgress()` records the signed-in reader’s chapter/page/position under a work-specific key. - Public work interactions include likes/favorites, follows, comments, replies, and notifications where supported by `src/lib/persistence.ts`. - Count displays must be calculated from persisted records, never hardcoded. ### Social and messaging Persistence types cover: ```ts Interaction CommentRecord NotificationRecord ReadingProgress ``` - Comments support work, volume, and chapter targets; replies use `parentId`. - Notifications are durable and can be individually or globally marked read. - Account follows and work follows are distinct key spaces; use the appropriate helper (`toggleAccountFollow` vs work follow helpers). - “Contact the manager” messages persist for the admin dashboard. Admin replies/deletions must use the message functions in `src/lib/persistence.ts`. ### Super Admin dashboard `src/components/AdminDashboard.tsx` is private and must remain absent from public navigation. - The admin route requires RBAC, not merely a hidden URL. - Unauthorized users must receive the existing protected-route behavior (403 or redirect), never dashboard data. - Dashboard manages profiles, all works, contact messages, admin content, featured artists, site logo, hero banner, site theme, and real site statistics. - Admin content types are `post`, `news`, `video`, `contest`, and `winner`. - Privileged mutations log through `window.genmb.audit.log()`. - Theme settings are persisted and applied through `document.documentElement.dataset.eventTheme`. - Logo updates dispatch/listen through the existing `site-logo-changed` browser event used by `AppShell`. ## Design Guidelines - **Style:** feminine, modern, calm sakura aesthetic with rounded surfaces, glassmorphism, soft shadows, and restrained motion. - **Palette:** light purple and violet as primary colors; white/near-white surfaces, dark foreground text, and pink sakura accents. Use semantic Tailwind tokens (`bg-primary`, `text-foreground`, `border-border`) rather than hardcoded colors. - **Typography:** use the `victorian` class for the Marisana Rose brand and major decorative headings only. Keep body/UI text highly legible, especially for Arabic. - **Background:** `SakuraPetals` in `src/App.tsx` supplies the decorative falling-petal layer. It must stay non-interactive (`aria-hidden`) and not block controls. - **Responsive:** mobile-first. Interactive controls have at least `min-h-11`; desktop navigation is hidden below `md`, where mobile menu behavior takes over. - **Directionality:** Arabic is default and sets `dir="rtl"`; English sets `dir="ltr"`. Prefer logical Tailwind utilities (`ps-*`, `pe-*`, `start-*`, `end-*`) over left/right-specific classes. - **Accessibility:** preserve visible focus rings, field labels, `aria-invalid`, screen-reader labels, toast live regions, and semantic button behavior in `src/components/ui.tsx`. ## App Flow 1. **Visitor** - Lands on `/`, sees the branded hero, latest/discovery sections, admin-managed content, and real zero-state/actual statistics. - Uses `/search` for published work discovery. - Opens public work/chapter pages without needing an account where content is published. 2. **New account** - Opens signup from the shell. - Chooses a unique username and submits email/password. - Verifies OTP through GenMB auth. - `AuthProvider` calls `ensureProfile()`; profile is durable across devices. 3. **Creator** - Signs in, opens the publishing/studio route. - Creates a work, uploads cover/banner directly from device, adds volumes and chapters. - Uploads multiple manga pages or writes novel text with optional images. - Reorders content, saves, then publishes. Only published copies appear in public search. 4. **Reader** - Opens a chapter, reads manga vertically or novel text. - Signed-in reading position is saved to durable progress. - Likes, follows, and comments create persisted interactions and notifications. 5. **Super Admin** - Navigates directly to the protected admin route; no public navigation link is provided. - RBAC check runs before dashboard access. - Reviews real statistics, moderates content, responds to messages, publishes site content, and manages visual branding/settings. ### Edge cases - Empty platform state is valid: render empty states and zero-derived counts, not placeholder works or fake engagement. - Upload failures must remain visible and retryable; never mark files as persisted until storage upload succeeds. - A work becomes publicly discoverable only when `published === true` and its `published-work:*` copy exists. - Logout must call both `window.genmb.auth.signOut()` and `window.genmb.rbac.clearRole()`. - Handle missing optional cover/banner/avatar/media gracefully with existing fallback UI. ## Conventions - Use TypeScript domain types from `src/lib/persistence.ts`; do not recreate incompatible local interfaces. - Components use PascalCase; hooks use `useX`; persistence operations use descriptive verbs such as `save`, `get`, `list`, `delete`, `toggle`, `count`, and `mark`. - Use `cn()` from `src/lib/utils.ts` for conditional Tailwind classes. - Reuse `Button`, `IconButton`, `Field`, `TextareaField`, `Card`, `EmptyState`, and dialog/toast primitives from `src/components/ui.tsx`. - Use Lucide icons only. - Keep UI translations in both `src/locales/ar.json` and `src/locales/en.json`; do not hardcode new interface copy where a localized key is appropriate. - Sanitize persisted text with `safeText()` and validate files through `window.genmb.storage.validate()` before upload. - For a new persistent feature: 1. Add backward-compatible types and key helpers in `src/lib/persistence.ts`. 2. Add exported persistence functions there, including authorization-aware ownership assumptions. 3. Build UI from shared components and use `Uploader` for media. 4. Add Arabic and English strings. 5. Add/extend routes in `src/App.tsx`. 6. If privileged, protect via `src/rbac.tsx`, audit mutations, and keep it out of public navigation. ## Platform (GenMB) This app is built and hosted on GenMB. **Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists. **Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime. **Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config. **Built-in services (relative API paths only, never hardcode domains):** - `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth - `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth` **File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file). **Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.