In our blog post Discover Citizen X - A Decentralied App to Annotate the Internet, we introduced CitizenX—a Chrome extension that empowers users to annotate webpages, engage in threaded discussions, and build a collaborative knowledge layer on the internet. While that post focused on the user experience, today we’re diving into the technology that powers CitizenX. If you’re a developer, tech enthusiast, or someone passionate about decentralized applications (dApps), this post is for you.
CitizenX is more than just a tool for web annotation; it’s a proof-of-concept for how decentralized technologies can transform collaborative tools. By leveraging Gun for distributed storage and peer-to-peer data management, we’ve created a platform that’s serverless, secure, and resilient. Curious to see it in action? You can check out our project deliverables on GitHub at https://github.com/Waltika/CitizenX and even try it out in Chrome’s developer mode before its official release on the Chrome Web Store. Let’s explore the tech behind CitizenX and what makes it a game-changer for decentralized web annotation.
CitizenX is built with a modern, robust tech stack designed to balance performance, scalability, and decentralization. Here’s a breakdown of the key components:
The CitizenX Chrome extension is developed using React and TypeScript, ensuring a modular, type-safe, and maintainable codebase. React powers the dynamic UI, allowing users to seamlessly interact with annotations, threaded comments, and profile settings. TypeScript adds an extra layer of reliability by catching errors during development, which is crucial for a project that will eventually scale to a global user base. The UI components, like the annotation input and settings menu, are designed to be minimal and non-intrusive, aligning with Chrome Manifest V3 requirements for a good user experience.
At the heart of CitizenX’s decentralization is Gun, a peer-to-peer protocol for storing and sharing data in a distributed file system. All annotations, comments, and user profiles are stored on IPFS, eliminating the need for a centralized server. This ensures that data is resilient—there’s no single point of failure—and users can access their contributions even if they switch devices or clear their browser data. IPFS also aligns with our non-functional requirement of zero installation beyond the Chrome extension, as it operates entirely within the browser environment.
To manage the collaborative aspects of CitizenX, we use Gun, a serverless, distributed, peer-to-peer database built on top of IPFS. Gun handles the storage and synchronization of annotations and comments across users. When you annotate a webpage, Gun ensures that your annotation is replicated to other users who have visited that page, creating a seamless collaborative experience. In future versions, we plan to optimize Gun replication so users only sync data for pages they’ve visited or annotated, reducing resource usage and improving scalability.
CitizenX implements decentralized authentication to ensure user identities are secure and portable. Instead of relying on a centralized server for user management, we use cryptographic techniques to create unique, device-agnostic identities. This means your profile—complete with a handle and profile picture—remains consistent across devices, even if you clear your browser data or lose your device. We’ve also taken steps to secure JWT tokens and other access mechanisms against hacking, aligning with our non-functional requirements for security.
To comply with Chrome Web Store policies and optimize performance, we use Vite for bundling our code. Vite’s tree-shaking and fast build times help us keep the extension bundle size under 100 MB (compressed), ensuring a lightweight footprint. All code is bundled locally, avoiding external fetches that could violate Chrome’s Content Security Policy (CSP) requirements under Manifest V3.
The decision to build CitizenX as a decentralized application (dApp) wasn’t just a technical choice—it’s a philosophical one. Centralized systems often come with trade-offs: single points of failure, data silos, and privacy concerns. By contrast, a decentralized approach offers several benefits that align with our vision for CitizenX:
This decentralized design makes CitizenX a robust platform for web annotation, setting the stage for future features like AI-powered structured data extraction and crypto-based incentives.
Building a Chrome extension in 2025 means adhering to Chrome Manifest V3 requirements, which prioritize security, performance, and user experience. Here’s how CitizenX meets these standards:
These measures not only ensure compliance but also make CitizenX a secure and performant tool for users and developers alike.
While we’re preparing CitizenX for its official release on the Chrome Web Store, tech enthusiasts and developers can already give it a try! Our project deliverables are available on GitHub at https://github.com/Waltika/CitizenX. Here’s how you can get started:
This early access lets you explore the decentralized web annotation experience before the official launch. We’d love to hear your feedback—feel free to open an issue on GitHub or contribute to the project!
CitizenX v1.0 is just the beginning. Our requirements for future versions include exciting technical advancements:
These advancements will make CitizenX a leader in decentralized collaborative tools, blending cutting-edge technology with community-driven innovation.
CitizenX is more than a Chrome extension—it’s a vision for a decentralized, collaborative web. By building on IPFS and Gun, we’re creating a platform that’s resilient, privacy-focused, and scalable. Whether you’re a developer interested in dApps, a tech enthusiast passionate about distributed systems, or a user looking for better collaborative tools, CitizenX has something for you.
Explore the project on GitHub at https://github.com/Waltika/CitizenX, try it out in developer mode, and join us in shaping the future of web annotation. Stay tuned for more updates as we approach our Chrome Web Store release, and let’s build a smarter, more connected internet together.
