Web App (PWA) Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• web/src/main.tsx
• web/vite.config.ts
• web/public/service-worker.js
• web/src/hooks/useMeshNetwork.ts
• web/README.md
• V1_READINESS.md
• V1_PRODUCTION_IMPLEMENTATION_PLAN.md
• BOOTSTRAP_VERIFICATION.md

The Sovereign Communications (SC) web application is a production-ready Progressive Web App (PWA) that serves as a client for the decentralized mesh network. It is built with a modern technology stack and designed to run entirely in the browser with no server dependencies for its core messaging functionality. The architecture prioritizes local-first data management, peer-to-peer communication, and offline capabilities.

The application integrates directly with the @sc/core library, which provides the foundational cryptography, peer management, and mesh networking logic. The web app's primary role is to provide a user interface, manage local data persistence, and handle browser-specific networking APIs like WebRTC.

Sources: web/README.md, IMPLEMENTATION_SUMMARY.md

Technology Stack

The web application is built using a modern, performant, and type-safe technology stack.

Technology	Version	Purpose
React	19.2	UI Framework for building the component-based interface.
Vite	5.0	Build tool for fast development and optimized production builds.
TypeScript	5.3	Language for type safety and improved code quality.
IndexedDB	N/A	Browser API for local, persistent storage of user data.
WebRTC	N/A	Browser API for real-time, peer-to-peer data channels.
CSS Modules	N/A	Scoped CSS for component styling, including a dark theme.

Sources: web/README.md:9-16, COMPLETION_STATUS.md:143-150

Project Structure

The web/ directory is organized to separate components, hooks, styles, and public assets. This structure supports a scalable and maintainable component-based architecture.

This diagram shows the key directories and files within the web application folder.

Sources: web/README.md:18-37

Build and Deployment

The application uses Vite for its build process. The configuration is defined in web/vite.config.ts.

Build Process

The production build is generated by running npm run build. This process transpiles the TypeScript/React code, bundles assets, and optimizes them for production. The output is placed in the web/dist/ directory.

This diagram illustrates the flow from the build command to the final output directory.

Sources: web/README.md:60-63, V1_READINESS.md:160-164

Deployment

The application is designed for static hosting. The contents of the dist/ directory can be deployed to any service like Netlify, Vercel, or GitHub Pages. Configuration files for Netlify (netlify.toml) and Vercel (vercel.json) are included to manage security headers and SPA redirect rules.

Sources: web/README.md:76-94

Application Entry Point

The application's entry point is web/src/main.tsx. This file is responsible for rendering the root React component, App.tsx, into the DOM. It uses React's StrictMode to highlight potential problems in the application during development.

// web/src/main.tsx:5-9
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import './index.css';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Sources: web/src/main.tsx

Core Logic and State Management

The heart of the web application's logic resides in the useMeshNetwork.ts custom hook. This hook encapsulates all interactions with the @sc/core library, managing the mesh network instance, peer connections, and message handling.

Key responsibilities of useMeshNetwork.ts:

• Initializing the MeshNetwork instance.
• Managing the user's identity.
• Handling peer connections and disconnections via WebRTC.
• Sending and receiving messages through the mesh.
• Interacting with IndexedDB for data persistence.
• Implementing an offline queue for messages that fail to send.

Sources: web/src/hooks/useMeshNetwork.ts, web/README.md:121-131

Message Sending Flow

The following diagram shows the sequence of events when a user sends a message.

This sequence illustrates how useMeshNetwork.ts attempts to send a message and utilizes the offline queue upon failure.

Sources: V1_PRODUCTION_IMPLEMENTATION_PLAN.md:460-496, web/src/hooks/useMeshNetwork.ts

Data Persistence

The PWA uses IndexedDB for all local data persistence, ensuring that user identity, contacts, and message history are retained across sessions. This local-first approach is fundamental to the application's decentralized nature.

IndexedDB Schema

The database schema is defined to store all critical user and network data.

This ER diagram outlines the object stores and their relationships within the IndexedDB database.

Sources: V1_READINESS.md:76-127, V1_PRODUCTION_IMPLEMENTATION_PLAN.md:460-496

Progressive Web App (PWA) Features

The application is a full-fledged PWA, with features that enable offline functionality and a native-like app experience.

Service Worker

A service worker is defined in web/public/service-worker.js. Its primary role is to cache static assets (self.__WB_MANIFEST), allowing the app to load instantly on subsequent visits, even without a network connection. It follows a cache-first strategy for precached assets.

This diagram shows the service worker's logic for handling network requests.

Sources: web/public/service-worker.js, V1_READINESS.md:167

Web App Manifest

The PWA includes a manifest.json file, which provides metadata about the application, such as its name, icons, and display mode. This allows users to "install" the web app to their home screen for easy access.

Sources: V1_READINESS.md:168, V1_COMPLETE_TASK_LIST.md:203-204

Mobile App Bootstrap Flow

A unique architectural feature is the ability for the web app to bootstrap the native Android application. This provides a seamless transition for users moving from the web to mobile, pre-populating the mobile app with discovered peers.

The flow is as follows:

1. The web app discovers peers and saves them to localStorage.
2. When the user clicks "Get Mobile App", the web app generates a deep link (sc://join?...).
3. This deep link contains the list of discovered peers, compressed and encoded in a bootstrap query parameter.
4. After installing the APK, the Android OS uses the deep link to launch the app.
5. The Android app parses the bootstrap data, retrieves the peer list, and automatically connects to the mesh network.

This diagram visualizes the seamless bootstrap process from the web app to the native Android client.

Sources: BOOTSTRAP_VERIFICATION.md

Conclusion

The SC Web App architecture is a robust, modern, and decentralized system. It leverages React and Vite for a high-performance user interface, while relying on browser standards like WebRTC and IndexedDB for its core P2P networking and data persistence. The inclusion of a service worker provides essential offline capabilities, and the innovative mobile bootstrap flow demonstrates a thoughtful approach to cross-platform user experience. This architecture establishes a solid foundation for a secure, serverless communication platform.

Sources: web/README.md, IMPLEMENTATION_SUMMARY.md