=== Repository Component Blueprint [source,text]

extracted_mangatsu/Mangatsu-0baf507c2ae1ce177b42de5a2340480848428926/ ├── public/ │ ├── sw.js # Service Worker managing offline media preloads │ └── manifest.webmanifest # Progressive Web App configuration matrix ├── src/ │ ├── components/ # Shared visual molecules (ZapButton, BlossomImage, BottomNav) │ ├── context/ # Global lifecycle hubs (NostrContext.tsx) │ ├── lib/ # Isolated business logic engines │ │ ├── blossom.ts # Blossom blob resolution & network availability checks │ │ ├── nip51.ts # Encrypted NIP-51 state serialization engine │ │ ├── offline.ts # Service worker cache control pipelines │ │ └── webp.ts # Client-side image re-encoding utilities │ ├── screens/ # Main interface routing screens │ │ ├── ComicDetail/ # Asset checking, chapter management, metadata views │ │ ├── Feed/ # Global, Follows, and Creator feeds with tag filtering │ │ ├── Library/ # Local drafts, active reading progress, synced bookmarks │ │ ├── Reader/ # Optimized mobile/desktop reading views with scroll snapping │ │ └── Upload/ # Step-by-step ingestion pipelines for CBZ and PDF files │ ├── services/ # Low-level networking transport boundaries │ │ ├── NostrService.ts # Relay/event-store publishing and subscriptions │ │ └── BlossomService.ts # Binary object transport controllers (file upload/resolve) │ ├── stores/ # Zustand atomic state slices │ └── main.tsx # Application composition root └── scripts/ # Distribution automation and deployment utilities

== 3. Nostr Data Model & Protocol Implementations

Mangatsu structures content and state across the decentralized network by repurposing existing Nostr event configurations alongside custom application definitions.

[cols=“1,1,2”, options=“header”] |=== | Nostr Event Kind | Specification Standard | Technical Application Within Mangatsu

| kind: 30040 | Custom App Spec | Comic Metadata Unit: A parameterized replaceable event that defines a comic’s core identity, housing the title, summary, cover art reference, creator credits, and search tags.

| kind: 30041 | Custom App Spec | Chapter Structural Mapping: A parameterized replaceable event linked directly to its parent kind: 30040 through explicit event tags. It contains an ordered sequence of page image hashes.

| kind: 30003 | NIP-51 Categorized Lists | Encrypted Bookmark Sync Layer: Uses a unique identifier (d=mangatsu-library). Encrypts and syncs saved bookmarked items directly across devices.

| kind: 10063 | NIP-Custom Blob Spec | Blossom Node Allocation: Defines the user’s personal network list of Blossom storage servers. Controls where files are read from or uploaded to.

| kind: 10002 | NIP-65 Relay Rules | Transport Routing Configuration: Dictates read/write routing priorities for cross-network state synchronization. |===

=== Session Management & Remote Cryptographic Signers Identity lifecycles are initialized within src/context/NostrContext.tsx and held in src/stores/authStore.ts. To ensure security across different use cases, Mangatsu accommodates four distinct login strategies:

. NIP-07 Browser Signers (window.nostr): Isolates private keys within dedicated extension contexts (e.g., Alby, nos2x) so that raw key files are never exposed to the application’s runtime. . NIP-46 Remote App Bunkers: Routes signing requests to an isolated remote key-management server over a secure WebSocket transport channel. . Automated QR Sign-in Bridges: Uses optical handshakes to pair mobile viewports to desktop environments over encrypted NIP-46 relay tunnels. . Local Ephemeral nsec Execution: Directly handles plain-text private keys in an active session memory slice for rapid setup during local development.

== 4. Blossom Network Strategy & Failover Resilience

To store large media files without using centralized clouds, Mangatsu uses Blossom servers—specialized file nodes designed for hosting high-volume binaries mapped directly to their cryptographic hashes.

=== Resilient Asset Delivery Pipelines When a chapter loads, src/lib/blossom.ts dynamically scans and gathers candidate storage servers from multiple sources:

. The publisher’s explicitly declared upload destination list. . The reader’s personalized kind: 10063 Blossom registry. . System default fallback nodes.

The custom BlossomImage element (src/components/BlossomImage.tsx) monitors media asset performance during playback. If a server drops offline or removes an image due to storage constraints, the engine triggers a failover sequence, automatically querying the remaining backup nodes for the missing hash. This setup ensures content remains highly available through partial data mirrors: as long as at least one server in the peer network holds the requested file hash, the client can seamlessly download and render the page.

== 5. Browser-Side Asset Processing Pipelines

To ensure absolute client independence, the ingestion pipeline inside src/screens/Upload/ completely bypasses server-side processing. Files are processed entirely within the browser sandbox environment before publication.

=== Asset Processing Flow . Archive/Document Deconstruction:

• Comic Book Zip (.cbz): Handled via asynchronous browser decompression engines. The tool extracts image components from the archive and orders them using alphanumeric sorting rules.
• Portable Document Format (.pdf): Processed via pdf.js integration inside src/screens/Upload/pdf.ts. The engine hooks into the file format, rendering individual vectors directly onto an offline HTML5 canvas element. . Dynamic Resolution Constraints: To prevent low-spec mobile hardware from running out of memory, strict operational boundaries are enforced via src/screens/Upload/limits.ts:
• Maximum Archive Size: 100 MB per file input pass.
• Maximum Page Allocation: 120 pages per unique chapter event.
• Canvas Normalization Target: If a page’s longest edge exceeds 2,000 pixels, the application downscales the canvas area while preserving the original aspect ratio. . WebP Re-encoding Engine: Normalized frame canvases are compressed into .webp images directly within the browser, lowering upload file sizes and optimizing bandwidth performance. . Concurrent Multi-Node Distribution: Completed images are sent in parallel to the user’s active Blossom servers. Once confirmed, successful host links are stored directly inside the final kind: 30041 chapter event metadata.

== 6. Bookmark Protection & Offline Storage Operations

=== Private Bookmark Sync via NIP-51 Cryptography User collections are kept private using the cryptographic standards defined in src/lib/nip51.ts and managed via src/stores/libraryStore.ts. When a user bookmarks a comic, the client downloads their current kind: 30003 list event, adds the new item, encrypts the entire list using the user’s public key, and broadcasts it to the network. This approach provides two key benefits:

• Absolute Privacy: External relay operators can only see encrypted blocks, preventing metadata leaks about reading preferences.
• Instant Cross-Device Sync: Logging into Mangatsu from an entirely new device automatically fetches, decrypts, and displays the user’s bookmarked collection without requiring a separate cloud configuration.

=== Offline Service Worker Cache Strategies Offline operations are handled via a dedicated Service Worker file (public/sw.js) combined with cache utility tools (src/lib/offline.ts). When a user activates the Offline Toggle on a comic’s dashboard, the software runs an automated caching routine:

[source,text]

User activates “Offline Reading Toggle” │ ├──► Fetches kind: 30040 (Comic Metadata) and caches cover image assets │ └──► Discovers associated kind: 30041 (Chapter Metadata Events) │ └──► Iterates through individual page SHA-256 hash entries │ └──► Runs background check across primary Blossom URLs │ └──► Streams asset binary directly into Service Worker Cache Storage

Once the files are saved, the system updates its status indicators. The reader can then open and read the comic entirely without an internet connection, bypassing network relays completely.

== 7. Developer & Operations Deployment Manual

=== Configuration Management The application consumes environment configuration parameters that can be customized during automated integration workflows or manual deployment stages:

[source,bash]

Core Environment Variables

Deploying to a Remote Host Example

1. Environment Dependency Initialization

npm install

2. Launch Local Reactive Development Environment (Vite Server)

npm run dev

3. Trigger Full Testing Suite (Vitest Framework Integration)

npm test

4. Compile Codebase for Static Build Out (Outputs to dist/)