# adiadd/socius architecture

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

- Interactive diagram: https://gitdiagram.com/adiadd/socius
- Repository: https://github.com/adiadd/socius

## Overview

##### Project Type and Purpose
- The README states “socius – anthropocentric scenarios for ai” which suggests that the project is a tool that generates or evaluates AI-related scenarios focusing on anthropocentric (human-centered) issues. Given the “prompts” (like ethics/trolley-problem and society/universal-basic-income) and “results” directories (storing outputs from various AI models like anthropic, google, openai), the project is essentially a prompt-based engine that interacts with different AI models to generate scenario responses.
- The project appears to have two main parts: a backend CLI/process side (under src) that runs prompts and collects results, and a frontend web application (in www) built with Next.js that likely displays and serves these results via API routes.

##### Analyzing the File Structure
- The top level shows a separation between the “src” folder and the “www” folder.
– The “src” folder contains the core logic:
- Entry points such as cli.ts and run-prompt.ts hint at a CLI/interpreter component.
- “src/models” holds files for different AI providers (anthropic.ts, google.ts, openai.ts, etc.), indicating that a strategy or adapter pattern may be applied based on which model is being queried.
- “src/prompts” organizes different scenario prompts into theme-based directories (ethics and society).
- “src/results” organizes the output per prompt and per model with timestamped JSON files.
- “src/utils” and “src/tests” further support the process via prompt-runner and result-formatting functions along with automated tests.
- Configuration (tsconfig.json, bun.lock, bunfig.toml, package.json) cements the development environment and build/deployment tooling.
– The “www” folder looks like a Next.js web application:
- It has a similar dependency structure with its own package.json, configuration files (next.config.ts, tsconfig.json, tailwind.config.js).
- The “www/src/app” directory shows Next.js API routes (e.g., under “api/scenarios”) and pages that render content.
- Components, hooks, utilities, and types indicate that this part is responsible for the presentation layer including UI components (scenario result cards, navigation, theme toggle, etc.) and data handling.

- Main Components:
– CLI/Backend Engine:
- CLI Entry Points:
- cli.ts – the starting point for processing prompts.
- run-prompt.ts – manages execution of prompt tasks.
- Models/Providers:
- Modules for different providers (anthropic, openai, google) abstract the API calls.
- Prompts and Templates:
- Organized prompt files (markdown files) in src/prompts.
- A generic prompt template in src/templates.
- Results Storage:
- Organized results directories capturing model outputs, structured by prompt category and timestamp.
- Supporting Infrastructure:
- Utility modules (prompt-runner, result-formatter) and tests ensuring robustness.
– Frontend Web Application:
- API Layer:
- Next.js API routes in www/src/app/api which serve scenario data. The routes are hierarchically structured by category, scenario, model, and date.
- Presentation and Static Pages:
- Pages under www/src/app display scenarios, render layouts for home, scenarios, and documentation.
- Components and Hooks:
- Reusable UI elements (collapsible sections, navigation, cards).
- Hooks (like use-mobile) and configuration (site config, theme provider) ensuring responsiveness and theming.

- Relationships and Data Flow:
– Data Creation:
- The CLI engine (via cli.ts) reads prompt files from src/prompts, sends them to respective model modules in src/models, and stores the responses as JSON files in src/results.
– Data Serving:
- The Next.js web app (www) reads these JSON results (and might process them via scripts like load-results.js) and exposes them through its API routes.
- Important Architectural Patterns:
– Separation of Concerns: Distinct separation between data processing (CLI/backend) and presentation (Next.js web app).
– Modular Design: Models and prompt handling are modular, allowing easy extensibility with additional providers or scenario types.
– File-based Data Persistence: Results are stored in a structured file system which is then processed by the web layer.
- Relevant Technologies/Frameworks:
– Bun (bun.lock, bunfig.toml) as the JavaScript runtime and package manager.
– TypeScript (tsconfig.json) for type safety.
– Next.js for building the web application.
– Tailwind CSS (tailwind.config.js) for styling in the web app.
– Node-based testing modules for automated tests.

## Diagram (Mermaid)

```mermaid
graph TD
    %% CLI/Backend Engine Subgraph
    subgraph "CLI/Backend Engine"
        direction TB
        %% Entry Points
        CLI1["cli.ts"]:::backend
        CLI2["run-prompt.ts"]:::backend
        subgraph "Entry Points"
            direction TB
            CLI1
            CLI2
        end

        %% Prompts Manager and Template
        PM["Prompts Manager"]:::backend
        PM_TP["trolley-problem.md"]:::backend
        PM_UBI["universal-basic-income.md"]:::backend
        TEM["Prompt Template"]:::backend
        subgraph "Prompts & Templates"
            direction TB
            PM
            PM_TP
            PM_UBI
            TEM
        end

        %% AI Models/Providers
        AI1["Anthropic Model"]:::backend
        AI2["Google Model"]:::backend
        AI3["OpenAI Model"]:::backend
        AI4["Models Config"]:::backend
        subgraph "AI Models/Providers"
            direction TB
            AI1
            AI2
            AI3
            AI4
        end

        %% Results Storage
        RS["Results Storage"]:::storage

        %% Utility Modules
        U1["Prompt Runner"]:::util
        U2["Result Formatter"]:::util
        subgraph "Utility Modules"
            direction TB
            U1
            U2
        end

        %% Testing Modules
        T["Testing Modules"]:::test

        %% Connections within Backend
        CLI1 -->|"initiate"| PM
        CLI2 -->|"initiate"| PM
        PM -->|"load"| PM_TP
        PM -->|"load"| PM_UBI
        PM -->|"apply"| TEM
        PM -->|"select"| AI1
        PM -->|"select"| AI2
        PM -->|"select"| AI3
        AI1 -->|"returns result"| RS
        AI2 -->|"returns result"| RS
        AI3 -->|"returns result"| RS
        AI4 ---|"configures"| AI1
        AI4 ---|"configures"| AI2
        AI4 ---|"configures"| AI3
        U1 -->|"supports"| PM
        U2 -->|"formats"| RS
        T ---|"validates"| CLI1
        T ---|"validates"| PM
    end

    %% Frontend Web Application Subgraph
    subgraph "Frontend Web Application"
        direction TB
        FAPI["API Layer"]:::frontend
        FUI["Web Pages"]:::frontend
        FCOMP["UI Components"]:::frontend
        subgraph "Frontend UI"
            direction TB
            FUI
            FCOMP
        end
        subgraph "Configurations & Scripts"
            direction TB
            W1["Next Config"]:::frontend
            W2["package.json"]:::frontend
            W3["Tailwind Config"]:::frontend
            W4["Load Results Script"]:::frontend
        end

        %% Frontend Connections
        RS ---|"provides JSON"| FAPI
        FAPI -->|"fetches"| FUI
        FAPI -->|"fetches"| FCOMP
    end

    %% Cross-layer connection annotation
    CLI1 ---|"CLI writes JSON results"| RS

    %% Click Events for CLI/Backend
    click CLI1 "https://github.com/adiadd/socius/blob/main/src/cli.ts"
    click CLI2 "https://github.com/adiadd/socius/blob/main/src/run-prompt.ts"
    click AI1 "https://github.com/adiadd/socius/blob/main/src/models/anthropic.ts"
    click AI2 "https://github.com/adiadd/socius/blob/main/src/models/google.ts"
    click AI3 "https://github.com/adiadd/socius/blob/main/src/models/openai.ts"
    click AI4 "https://github.com/adiadd/socius/blob/main/src/models/config.ts"
    click PM "https://github.com/adiadd/socius/tree/main/src/prompts/"
    click PM_TP "https://github.com/adiadd/socius/blob/main/src/prompts/ethics/trolley-problem.md"
    click PM_UBI "https://github.com/adiadd/socius/blob/main/src/prompts/society/universal-basic-income.md"
    click TEM "https://github.com/adiadd/socius/blob/main/src/templates/prompt-template.md"
    click RS "https://github.com/adiadd/socius/tree/main/src/results/"
    click U1 "https://github.com/adiadd/socius/blob/main/src/utils/prompt-runner.ts"
    click U2 "https://github.com/adiadd/socius/blob/main/src/utils/result-formatter.ts"
    click T "https://github.com/adiadd/socius/tree/main/src/tests/"

    %% Click Events for Frontend Web Application
    click FAPI "https://github.com/adiadd/socius/tree/main/www/src/app/api/"
    click FUI "https://github.com/adiadd/socius/tree/main/www/src/app/"
    click FCOMP "https://github.com/adiadd/socius/tree/main/www/src/components/"
    click W1 "https://github.com/adiadd/socius/blob/main/www/next.config.ts"
    click W2 "https://github.com/adiadd/socius/blob/main/www/package.json"
    click W3 "https://github.com/adiadd/socius/blob/main/www/tailwind.config.js"
    click W4 "https://github.com/adiadd/socius/blob/main/www/scripts/load-results.js"

    %% Styles
    classDef backend fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef frontend fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef storage fill:#abebc6,stroke:#333,stroke-width:2px;
    classDef util fill:#d2b4de,stroke:#333,stroke-width:2px;
    classDef test fill:#f5b7b1,stroke:#333,stroke-width:2px;
```
