Monorepo for Agora Citizen Network.
We are at a critical moment where social media platforms are increasingly evolving into tools of computational propaganda (the use of bots and algorithms to manipulate public opinion), polarizing society, and threatening democratic values worldwide. Recent advancements in AI have unfortunately accelerated this dangerous trend.
Agora Citizen Network was born out of our belief that digital public spaces must be intentionally designed to strengthen the social fabric of our societies. We envision a future where technology transforms social diversity into a catalyst for progress, rather than a driver of division.
- Using zero-knowledge proof (ZKP) cryptography, Agora allows users to anonymously prove they are human - not bots - without disclosing any personal information to anyone, including us.
- Besides, most social networks today use engagement-based ranking algorithms designed to maximize user attention and engagement. Unfortunately, these algorithms often promote polarizing content, which tends to attract the most attention, whether good or bad. In contrast, Agora employs bridging-based ranking algorithms that aim to highlight content appreciated by users across different political viewpoints. The goal is not to censor extreme opinions but to preserve a rich diversity of viewpoints and identify common ground.
- Additionally, we plan to build on top of DDS (Decentralized Deliberation Standard), an open protocol for sovereign, verifiable, interoperable, and resilient deliberation at scale. DDS is built on AT Protocol for transport, decentralized storage for archival, and Ethereum for tamper-evident verification.
Check out and vote on the roadmap here
Install:
For detailed information about each service, licenses, and documentation, see COPYING-README.md.
Agora - A Quasar application (Vue.js frontend) providing the user interface for Agora Citizen Network.
API - A Fastify application supported by a PostgreSQL database. Main backend API handling user requests, authentication, voting, and conversation management.
Math Updater - Python background worker that runs red-dwarf opinion-group analysis and generates AI-powered cluster insights using LLM models.
AI Description Retry Worker - Python worker that retries and backfills AI-generated opinion-group labels and summaries requested by analysis views.
Description Translation Retry Worker - Python worker that retries and backfills translated opinion-group labels and summaries for requested display languages.
Import Worker - Python worker that consumes conversation import jobs and imports Polis URLs or CSV archives.
Scoring Worker - Python worker that runs Solidago algorithm to produce community rankings from MaxDiff (Best-Worst Scaling) comparisons. Uses Valkey for job queuing and supports parallel scoring.
Shared - Common TypeScript code synced to TypeScript services and used as a source for generated Python worker artifacts.
Shared App-API - TypeScript code shared specifically between the frontend (agora) and API service.
Shared Backend - Backend-specific TypeScript code for the API and source schema for generated Python worker artifacts.
Python Worker Shared - Shared Python package used by background workers for generated models/types, queue helpers, retry logic, AI providers, and red-dwarf integration.
LLM - LLM prompts and Python scripts for AI-related development.
We generate an openapi-zkorum.json file from the backend, and then use openapi-generator-cli to generate the corresponding frontend client.
Please read READMEs in /services/agora, /services/api, /services/import-worker, /services/math-updater, and /services/scoring-worker.
Frontend App:
make dev-app
Backend API:
make dev-api
Import Worker:
make dev-import-worker
Root make dev-* targets write durable logs under .local/logs while still streaming output to the terminal or kitty tab.
make logs
make logs-tail service=api
make logs-cleanLog layout:
.local/logs/runs/<run-id>/<service>.logstores each captured service run..local/logs/latest/<service>.logpoints to the latest run for quick inspection..local/logs/latest/<service>.events.jsonlstores semantic load-test events emitted withAGORA_LOAD_EVENT..local/logs/latest/<service>-browser.jsonlstores dev-browser events emitted by the Quasar frontend..local/logs/latest/<service>.summary.jsonstores k6 summaries when available.
Use rg directly for searches, for example rg "error|failed" .local/logs/latest/api.log. Logs rotate at 25 MB per file, keep 5 files per service, prune runs older than 7 days, and cap total run storage at 750 MB by default. Override with AGORA_LOG_DIR, AGORA_LOG_RUN_ID, AGORA_LOG_MAX_BYTES, AGORA_LOG_MAX_FILES, AGORA_LOG_RETENTION_DAYS, or AGORA_LOG_MAX_TOTAL_BYTES.
run_all_in_kitty_tabs.sh exports one shared AGORA_LOG_RUN_ID, so all tabs from the same launch land in the same run directory.
Some typescript source files are shared directly without using npm packages - by copy-pasting using rsync.
Use these commands to automatically rsync shared files to back and front:
make dev-sync
Automatically generate frontend stub from backends and subsequent openapi changes:
make dev-generate
... and start coding!
Refer to the embed documentation.
If you discover any security issues, please send an email to security@zkorum.com. The email is automatically CCed to the entire team, and we'll respond promptly. See SECURITY for more info.
See CONTRIBUTING.md
See COPYING-README
This project has received funding from the European Union's Horizon Europe 2020 research and innovation program through the NGI TRUSTCHAIN program under cascade funding agreement No. 101093274 and the NGI SARGASSO project under grant agreement No. 101092887.
In terms of source code, the NGI SARGASSO program exclusively funded the integration with Rarimo. For detailed information, please refer to the commit messages and file headers.