# openai/democratic-inputs architecture

> Architecture diagram of the GitHub repository openai/democratic-inputs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openai/democratic-inputs
- Repository: https://github.com/openai/democratic-inputs

## Overview

##### Project type and purpose
- This is a “meta-project” or monorepo: an umbrella repository that houses ten different grant-funded subprojects, each with its own codebase (web apps, data pipelines, docs, notebooks, backends, etc.).
- The root README is purely an index of projects; each project folder (e.g. “Aligned-Platform-EnergizeAI”, “deliberation_at_scale”, “case_law_for_ai_policy”, etc.) is self-contained and implements its own architecture.

##### File structure
- Top-level:
- README.md – table of contents pointing to each project
- /projects – container for ten independent subdirectories
- Each /projects/<project> usually follows one of these patterns:
- Full-stack Next.js or Remix web application (e.g. Aligned-Platform-EnergizeAI, democratic_fine_tuning, inclusive_ai…)
- Serverless or Firebase functions + hosting (rappler_aidialogue)
- Pure frontend React/Vite app (Ubuntu_AI)
- Python/Jupyter notebooks and scripts (case_law_for_ai_policy, collective_dialogues_for_democratic_input, taxonomybuilder)
- Polyrepo (Nx) micro-monorepo with data layer, edge-functions, frontend, orchestrator services (deliberation_at_scale)
- Look for:
- package.json, tsconfig.json, bun.lock or pnpm-lock – indicates a JS/TS app
- /src, /app, /pages, /components – Next.js or React structure
- /functions, /hosting – Firebase serverless
- /migrations, /schema.prisma – database schema and migrations
- .ipynb, .py – Jupyter notebooks and Python scripts
- docs, public, assets – static documentation or assets

##### Extract insights from each subproject’s README
- Often describes the stack (e.g. “Next.js 13 + Supabase + Graphile”, “Remix + Prisma + Tailwind”, “Vite + Firebase”, “FastAPI or Flask backend + React frontend”)
- May mention external services: OpenAI API, Supabase, Firebase, Web3Auth, GraphQL endpoint, Sentry, Whereby, etc.

a. Main components (at two levels):
– Frontend (React/Next.js/Remix/Vite)
– Backend/API (Node.js/Edge functions/Firebase functions/Python server)
– Database/Data store (Postgres via Drizzle/Prisma, Supabase, Firestore, local CSV or JSON, Jupyter data files)
– Batch jobs, notebooks or ETL scripts (Python notebooks, migrations, taxonomy builder)
– External services (OpenAI API, Web3Auth, Whereby video calls, Supabase Realtime, Graphile Worker, Sentry)

b. Component relationships

c. Architectural patterns & design principles
- Monorepo, but no shared code cross-project (each has its own package.json)
- Separation of concerns: UI / business logic / data / docs
- Use of serverless functions for scalability and low-maintenance compute
- Event-driven or job-queue patterns in “deliberation_at_scale” orchestrator
- Client-heavy apps (Jupyter notebooks and React UIs) coupled to lightweight backends

d. Key technologies & frameworks
- Next.js, Remix, Vite, React
- Firebase Hosting & Functions, Supabase, Drizzle ORM, Prisma
- Jupyter, Python scripts, CSV/JSON data
- GraphQL (codegen, graphql.tsx), Apollo or SWR clients
- Tailwind CSS, PostCSS
- Web3Auth, ERC-20 contracts (Inclusive.AI)
- OpenAI API calls (energize-engine, chatgpt.js)
- Orchestrator: Node.js + graphile-worker + Supabase + Sentry + Whereby

- Blue = frontend/UI
- Green = backend/API
- Orange = database/data store
- Purple = external services/APIs
- Gray = batch jobs/notebooks

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Monorepo"
        direction TB
        README["README.md"]:::gray
        Projects["projects/"]:::gray
    end
    README --> Projects

    subgraph "Projects Container"
        direction TB
        APE["Aligned-Platform-EnergizeAI"]:::module
        Ubuntu["Ubuntu_AI_a_platform_for_equitable_and_inclusive_model_training"]:::module
        CaseLaw["case_law_for_ai_policy"]:::module
        Collective["collective_dialogues_for_democratic_input"]:::module
        Deliberation["deliberation_at_scale"]:::module
        DemFine["democratic_fine_tuning"]:::module
        Inclusive["inclusive_ai_chatgpt_plugin_and_dao_to_engage_marginalized_groups_in_ai"]:::module
        Rappler["making_ai_transparent_and_accountable (rappler_aidialogue)"]:::module
    end

    Projects --> APE
    Projects --> Ubuntu
    Projects --> CaseLaw
    Projects --> Collective
    Projects --> Deliberation
    Projects --> DemFine
    Projects --> Inclusive
    Projects --> Rappler

    %% Aligned-Platform-EnergizeAI detail
    subgraph "Aligned-Platform-EnergizeAI"
        direction TB
        APE_FE["Frontend (Next.js)"]:::frontend
        APE_AGG["Aggregation Pipelines"]:::batch
        APE_TAX["Taxonomy Builder"]:::batch
        APE_FE -->|"uses data from"| APE_AGG
        APE_FE -->|"generates taxonomy via"| APE_TAX
    end
    click APE_FE "https://github.com/openai/democratic-inputs/tree/main/projects/Aligned-Platform-EnergizeAI/app"
    click APE_AGG "https://github.com/openai/democratic-inputs/tree/main/projects/Aligned-Platform-EnergizeAI/aggregation"
    click APE_TAX "https://github.com/openai/democratic-inputs/blob/main/projects/Aligned-Platform-EnergizeAI/taxonomybuilder/tbm.py"

    %% Ubuntu AI detail
    subgraph "Ubuntu_AI Frontend"
        direction TB
        Ubuntu_FE["Pure Frontend (Vite + React)"]:::frontend
    end
    click Ubuntu_FE "https://github.com/openai/democratic-inputs/tree/main/projects/Ubuntu_AI_a_platform_for_equitable_and_inclusive_model_training/frontend/frontend"

    %% case_law_for_ai_policy detail
    subgraph "case_law_for_ai_policy"
        direction TB
        CL_Data["Data & Preprocessing"]:::batch
        CL_Notebooks["Jupyter Experiments"]:::batch
        CL_Docs["Static Docs"]:::batch
        CL_BE["Backend Server"]:::backend
        CL_FE["Frontend Prototype"]:::frontend
        CL_Data --> CL_Notebooks
        CL_Notebooks --> CL_BE
        CL_BE -->|"serves UI to"| CL_FE
    end
    click CL_Data "https://github.com/openai/democratic-inputs/tree/main/projects/case_law_for_ai_policy/data"
    click CL_Notebooks "https://github.com/openai/democratic-inputs/tree/main/projects/case_law_for_ai_policy/case-tools"
    click CL_Docs "https://github.com/openai/democratic-inputs/tree/main/projects/case_law_for_ai_policy/docs"
    click CL_BE "https://github.com/openai/democratic-inputs/blob/main/projects/case_law_for_ai_policy/interactive/backend/server.py"
    click CL_FE "https://github.com/openai/democratic-inputs/tree/main/projects/case_law_for_ai_policy/interactive/frontend"

    %% collective_dialogues_for_democratic_input detail
    subgraph "collective_dialogues_for_democratic_input"
        direction TB
        CD_Exp["Experiment Notebooks & CSVs"]:::batch
        CD_Tools["Support Tools"]:::batch
        CD_Exp --> CD_Tools
    end
    click CD_Exp "https://github.com/openai/democratic-inputs/tree/main/projects/collective_dialogues_for_democratic_input/experiments"
    click CD_Tools "https://github.com/openai/democratic-inputs/tree/main/projects/collective_dialogues_for_democratic_input/tools"

    %% deliberation_at_scale detail
    subgraph "deliberation_at_scale"
        direction TB
        DAS_Data["Data Layer (Drizzle ORM)"]:::database
        DAS_Edge["Edge Functions"]:::backend
        DAS_FE["Frontend (Next.js + GraphQL)"]:::frontend
        DAS_Orch["Orchestrator Service"]:::backend
        DAS_Data --> DAS_Edge
        DAS_Edge --> DAS_FE
        DAS_Orch --> DAS_Data
    end
    click DAS_Data "https://github.com/openai/democratic-inputs/tree/main/projects/deliberation_at_scale/packages/data-core"
    click DAS_Edge "https://github.com/openai/democratic-inputs/tree/main/projects/deliberation_at_scale/packages/edge-functions"
    click DAS_FE "https://github.com/openai/democratic-inputs/tree/main/projects/deliberation_at_scale/packages/frontend"
    click DAS_Orch "https://github.com/openai/democratic-inputs/tree/main/projects/deliberation_at_scale/packages/orchestrator"

    %% democratic_fine_tuning detail
    subgraph "democratic_fine_tuning"
        direction TB
        DF_App["Remix Full-stack App"]:::frontend
        DF_Schema["Prisma Schema"]:::database
        DF_Mig["Migrations"]:::database
        DF_Data["Survey Data"]:::database
        DF_App --> DF_Schema
        DF_Schema --> DF_Mig
        DF_App --> DF_Data
    end
    click DF_Schema "https://github.com/openai/democratic-inputs/blob/main/projects/democratic_fine_tuning/schema.prisma"
    click DF_Mig "https://github.com/openai/democratic-inputs/tree/main/projects/democratic_fine_tuning/migrations"
    click DF_Data "https://github.com/openai/democratic-inputs/tree/main/projects/democratic_fine_tuning/data"

    %% inclusive_ai detail
    subgraph "inclusive_ai_chatgpt_plugin_and_dao"
        direction TB
        IA_FE["Next.js ChatGPT Plugin UI"]:::frontend
    end
    click IA_FE "https://github.com/openai/democratic-inputs/tree/main/projects/inclusive_ai_a_chatgpt_plugin_and_dao_to_engage_marginalized_groups_in_ai/Inclusive.AI app/website"

    %% rappler_aidialogue detail
    subgraph "making_ai_transparent_and_accountable (rappler_aidialogue)"
        direction TB
        RA_FE["Hosted Frontend"]:::frontend
        RA_FN["Serverless Functions"]:::backend
        RA_FE --> RA_FN
    end
    click RA_FN "https://github.com/openai/democratic-inputs/tree/main/projects/making_ai_transparent_and_accountable/rappler_aidialogue/functions"
    click RA_FE "https://github.com/openai/democratic-inputs/tree/main/projects/making_ai_transparent_and_accountable/rappler_aidialogue/hosting"

    classDef monorepo fill:#f0f0f0,stroke:#333,stroke-width:2px
    classDef module fill:#e8e8e8,stroke:#555,stroke-width:1px
    classDef frontend fill:#ADD8E6,stroke:#036,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#036,stroke-width:1px
    classDef database fill:#FFA500,stroke:#963,stroke-width:1px
    classDef batch fill:#D3D3D3,stroke:#666,stroke-width:1px
    classDef gray fill:#CCCCCC,stroke:#333,stroke-width:1px
```
