CIVIC OS Documentation

Everything you need to know about how the platform works — features, roles, processes, and the long-term vision.

1. Overview & Vision

CIVIC OS is a citizen-powered civic engagement platform that gives communities the tools to self-organize, identify problems, propose solutions, and hold delegates accountable. It is designed as a permanent civic infrastructure — not just an election-day tool.

The core idea: democracy works best when citizens are engaged year-round, not just once every four years. CIVIC OS provides the digital infrastructure for continuous civic participation at the district level.

Core Principles

  • Transparency: All activity is public. Every vote, problem, solution, and comment is visible to the community.
  • Forced Tradeoffs: With only 10 priority points, citizens must genuinely prioritize instead of "liking" everything.
  • Competence over Loyalty: Delegates are evaluated based on their track record of solutions, not party affiliation.
  • Anti-Manipulation by Design: Multiple layers of protection against gaming, astroturfing, and coordinated attacks.

2. Districts (Multi-Tenancy)

CIVIC OS organizes civic participation around districts — geographic communities that mirror real-world political boundaries. Each district operates as its own community with its own problems, solutions, and priority balance.

How Districts Work

  • Admin-configured: Administrators create and manage districts with names, descriptions, and seat counts.
  • Membership: Each user belongs to one district. You can change your district at any time in Settings.
  • Seat Count: Represents the number of delegate seats for that district, reflecting its representation capacity.
  • Category Balance: Each district shows a real-time visualization of how priority points are distributed across categories (infrastructure, education, health, etc.).

Joining a District

You can select a district when registering or change it later in Settings. Once you join a district, you can see its problems, propose solutions, and allocate your priority points to issues that matter to you.

3. Problems

Problems are the foundation of CIVIC OS. They represent real issues identified by citizens in their district.

Reporting a Problem

  • Any member who has passed the 14-day cooldown can report a problem.
  • Problems have a title, detailed description, optional category, and optional location.
  • Once submitted, the problem appears in the district hub for all members to see.

Confirming & Disputing

Other citizens can confirm or dispute a problem based on their direct experience. This community verification helps surface real problems while flagging potential false reports. Confirmation counts are displayed alongside each problem.

Problem Status

  • Open: Newly reported, seeking confirmations and solutions.
  • In Progress: A solution is being implemented.
  • Resolved: The problem has been addressed.

4. Priority Points

Every citizen receives 10 priority points. These points represent your civic attention budget — you distribute them across the problems that matter most to you.

How It Works

  • 10 points total: You can spread them across multiple problems or go all-in on one issue.
  • Reallocate anytime: As your priorities change, you can redistribute your points freely.
  • Real tradeoffs: Putting 5 points on one problem means only 5 remain for everything else. This forces genuine prioritization.

Category Balance

The district hub shows a real-time visualization of how priority points are distributed across categories. This creates community awareness: "47% of our attention goes to infrastructure, but only 2% to education." No one is forced to change, but the transparency invites reflection.

5. Solutions & Ratings

Anyone can propose a solution to a problem. Solutions include a title, detailed description, estimated cost, and the responsible institution.

Two-Axis Rating System

Each solution is rated on two independent axes:

  • Feasibility (1-5): How realistic and implementable is this solution?
  • Desirability (1-5): How much does the community want this solution?

This two-axis approach reveals important nuances: a solution might be highly desirable but impractical, or very feasible but unpopular. The scatter plot visualization shows both community and expert ratings at a glance.

Expert Ratings

Verified experts' ratings are displayed separately from community ratings. This means the community can see both "what citizens want" and "what experts recommend" — without either group overriding the other.

6. Expert Roles

CIVIC OS has a special expert role for users with verified domain knowledge. Experts don't get extra votes — their ratings are simply displayed separately.

Becoming an Expert

  1. Go to Settings and submit an expertise claim for a specific category.
  2. Describe your qualifications, experience, and education.
  3. An administrator reviews and approves or rejects the claim.

How Expert Opinions Are Shown

On each solution's detail page, you'll see community ratings and expert ratings separately. For example: "Community: Feasibility 3.2, Desirability 4.5 | Experts: Feasibility 2.1, Desirability 3.8." This gives citizens more information to make informed decisions.

7. Discussions

Every problem and solution has its own discussion thread. This keeps conversations focused and organized.

  • Threaded comments: Reply directly to specific comments to keep conversations organized.
  • No general chat: Every discussion is attached to a specific problem or solution, preventing off-topic drift.
  • AI moderation: Comments are automatically screened for hate speech, misinformation, and manipulation.
  • Moderator tools: Moderators can hide comments that violate community standards.

8. AI Moderation

CIVIC OS uses AI to assist with content moderation. The AI does not censor — it flags content for human review.

How It Works

  • Every comment is analyzed by AI upon submission.
  • The AI checks for hate speech, misinformation, manipulation attempts, and other harmful content.
  • Flagged comments include an explanation of why they were flagged.
  • Flagged content appears in the admin Moderation Queue for review.
  • Moderators and admins decide whether to hide flagged content — the AI only advises.

Transparency

AI flags are visible to users, so the community can see when and why content was flagged. This transparency builds trust in the moderation process.

9. Anti-Manipulation

Online civic platforms are prime targets for manipulation. CIVIC OS implements multiple layers of defense:

  • 14-Day Cooldown: New accounts can read and comment, but cannot vote, submit problems, or allocate priority points for 14 days. This makes astroturfing campaigns slow and expensive.
  • Transparent Activity History: Every user's complete activity is public — there are no anonymous votes or hidden agendas. Bad actors can't hide behind anonymity.
  • Anomaly Detection: Sudden bursts of new accounts all prioritizing the same issue trigger alerts for moderator review.
  • AI Moderation: Automated screening of comments for manipulation patterns.
  • Open Source: The entire codebase is open source, allowing anyone to verify there is no hidden bias or manipulation in the platform itself.

10. User Roles & Permissions

CIVIC OS has four user roles with different capabilities:

Permission Citizen Expert Moderator Admin
Read problems & solutions
Comment
Report problems *
Vote & allocate points *
Expert-tagged ratings
Hide/unhide comments
Manage districts
Manage users & roles
Approve expert claims

* Requires 14-day cooldown period for citizens. Admins and moderators bypass the cooldown.

11. Full Vision & Roadmap

CIVIC OS is designed as a 5-layer civic operating system, to be built in 5 phases:

The 5 Layers

Layer 1: Portal + District Communities

Basic civic infrastructure — districts, problems, solutions, priority points, discussions, and user roles. This is the current implementation.

Layer 2: Delegates & Accountability

Citizens select delegates for each district based on competence. Delegates have public mandates, term limits, and performance tracking.

Layer 3: Participatory Budgeting

Citizens participate in allocating real budgets to solutions. Transparent tracking of how money is spent and what outcomes are achieved.

Layer 4: Inter-District Collaboration

Districts can collaborate on shared problems, pool resources, and learn from each other's solutions.

Layer 5: National Integration

Aggregated data from all districts informs national policy. The platform becomes a permanent feedback loop between citizens and governance.

Development Phases

Phase 1: Foundation (Current)

Core platform with districts, problems, solutions, priority points, ratings, discussions, AI moderation, and multi-language support.

Phase 2: Delegate System

Delegate nominations, voting, mandate tracking, and accountability dashboards.

Phase 3: Budget Integration

Participatory budgeting tools, expense tracking, and outcome measurement.

Phase 4: Cross-District

Federation between districts, shared solution libraries, and collaborative problem-solving.

Phase 5: Scale & Integration

National dashboards, API integrations with government systems, and advanced analytics.