# lilmgenius/polysona architecture

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

- Interactive diagram: https://gitdiagram.com/lilmgenius/polysona
- Repository: https://github.com/lilmgenius/polysona

## Overview

1. **What this repo is**
   - Polysona is a **persona orchestration workspace** for AI agents, not a conventional app.
   - The core idea is a **setup phase** that extracts a user persona, then a **repeatable content loop** that uses that persona across different AI agents and hosts.

2. **Top-level architecture**
   - The repository is split into four main planes:
     - **Persona/agent definitions** in `agents/`, `personas/`, and `skills/`
     - **Local dashboard UI** in `client/`
     - **Local API/server** in `server/`
     - **Generated and operational artifacts** in `content/` and `decks/`
   - Around that, there is host integration for **Codex** and **Claude Code** via `AGENTS.md`, `.claude-plugin/`, and `hooks/`.

3. **Persona data layer**
   - Persona state is stored as plain markdown under `personas/default/`:
     - `persona.md` for the core persona
     - `nuance.md` for subtle traits or tones
     - `accounts.md` for account/platform context
   - This is the main persistent input that downstream agents consume, and it is intentionally file-based so it can be reused across tools.

4. **Agent pipeline**
   - The README’s architecture maps to five named agents in `agents/`:
     - **profiler**: interviews and extracts persona signals
     - **trendsetter**: collects trend topics
     - **content-writer**: generates platform-specific drafts
     - **virtual-follower**: simulates audience QA and ranks outputs
     - **admin**: handles publish/tracking steps
   - The repo treats these as distinct responsibilities, so the persona extraction, content generation, QA, and publishing phases are separated.

5. **Content lifecycle and storage**
   - Content artifacts move through `content/` subfolders:
     - `drafts/`
     - `qa/`
     - `published/`
     - `trends/`
   - This creates a clear data flow from trend discovery to draft generation, QA review, and publication.
   - The pipeline is file-oriented, which makes state easy to inspect and portable between AI tools.

6. **Dashboard/UI layer**
   - `client/` is a **Vite + React + TypeScript** frontend.
   - Pages like `Home`, `Personas`, `PersonaDetail`, `AgentMonitor`, `ContentPipeline`, and `VirtualFollower` suggest the UI is a **local observability dashboard** for the persona system.
   - Components such as `AgentStatusCard`, `GapAnalysis`, `InterviewTimeline`, `FrameworkCoverage`, and `ContentQualityMeter` indicate the UI is focused on **pipeline visibility, persona analysis, and QA inspection** rather than end-user content consumption.

7. **Server/API layer**
   - `server/index.ts` and `server/routes/api.ts` expose the backend for the dashboard and workspace interactions.
   - `server/lib/ploon.ts` appears to hold shared server-side domain logic for the Polysona system.
   - The server likely acts as the bridge between the UI and the filesystem-based workspace state: personas, content folders, and status metadata.

8. **Host integration boundaries**
   - This repo is designed to run inside multiple AI environments:
     - **Codex** via `AGENTS.md` and synced skills
     - **Claude Code** via `.claude-plugin/marketplace.json` and `plugin.json`
   - `hooks/` provides lifecycle hooks like session start and pre/post tool use, which means the repo can shape agent behavior without hardcoding that logic into the app.

9. **Skill system**
   - `skills/` contains command-oriented agent instructions grouped by capability:
     - `interview`
     - `introduce`
     - `trend`
     - `content`
     - `qa`
     - `publish`
     - `status`
     - `export`
   - These are the operational “verbs” of the system, and `scripts/sync-codex-skills.mjs` mirrors them into Codex’s expected layout.
   - This is an important portability boundary: the same workflow is exposed through different agent runtimes, but the content lives in one repo.

10. **Generated/presentational artifacts**
   - `decks/` contains static slide decks and HTML viewers, likely for demos or product presentation.
   - `assets/` contains branding assets used by the docs and UI.
   - `process_svg.py` suggests some asset preprocessing in the build/content workflow.

11. **End-to-end data flow**
   - The main flow is:
     - interview/extract persona → write structured persona files
     - collect trends → create drafts
     - QA drafts with a simulated follower persona
     - publish and track outcomes
   - The dashboard provides visibility into that loop, while the filesystem holds the durable state.

12. **How to think about the architecture**
   - This is best drawn as a **local-first orchestration system** with a UI and API wrapped around a **filesystem-backed multi-agent workflow**.
   - The key boundaries are:
     - **persona definition vs. content generation**
     - **agent instructions vs. generated outputs**
     - **host-specific integration vs. portable repo assets**
   - The repo’s main value is not a single app feature, but the repeatable pipeline connecting those layers.

Main entry points: [`agents`](https://github.com/lilmgenius/polysona/tree/main/agents) (Agent specs), [`content`](https://github.com/lilmgenius/polysona/tree/main/content) (Content pipeline), [`skills`](https://github.com/lilmgenius/polysona/tree/main/skills) (Skills library), [`server`](https://github.com/lilmgenius/polysona/tree/main/server) (API server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host_integration["Host integration"]
  node_host_hooks["Hooks"]
  node_claude_plugin["Claude plugin<br/>claude config<br/>[.claude-plugin]"]
  node_codex_sync["Codex sync<br/>sync script"]
end

subgraph group_persona_agent_layer["Persona and agents"]
  node_persona_store["Persona store<br/>markdown state"]
  node_persona_core["Core persona<br/>persona file<br/>[persona.md]"]
  node_persona_nuance["Nuance notes<br/>persona file<br/>[nuance.md]"]
  node_persona_accounts["Account context<br/>persona file<br/>[accounts.md]"]
  node_agent_specs["Agent specs<br/>agent definitions"]
  node_profiler_agent["Profiler<br/>agent role<br/>[profiler.md]"]
  node_trendsetter_agent["Trendsetter<br/>agent role<br/>[trendsetter.md]"]
  node_writer_agent["Content writer<br/>agent role<br/>[content-writer.md]"]
  node_follower_agent["Virtual follower<br/>agent role"]
  node_admin_agent["Admin<br/>agent role<br/>[admin.md]"]
  node_skills_library["Skills library<br/>skill pack"]
  node_interview_skill["Interview<br/>skill<br/>[SKILL.md]"]
  node_content_skill["Content<br/>skill<br/>[SKILL.md]"]
  node_qa_skill["QA<br/>skill<br/>[SKILL.md]"]
  node_publish_skill["Publish<br/>skill<br/>[SKILL.md]"]
end

subgraph group_workspace_runtime["Workspace runtime"]
  node_dashboard["Dashboard<br/>vite react ui"]
  node_server_api["API server<br/>ts backend"]
  node_ploon_domain["Ploon logic<br/>server domain<br/>[ploon.ts]"]
end

subgraph group_artifacts_layer["Artifacts"]
  node_content_pipeline[("Content pipeline<br/>artifact flow")]
  node_drafts["Drafts<br/>content stage"]
  node_qa_outputs["QA outputs<br/>content stage"]
  node_published_content["Published<br/>content stage"]
  node_trend_inputs["Trends<br/>content stage"]
  node_deck_assets["Decks<br/>presentation assets"]
end

node_persona_store -->|"contains"| node_persona_core
node_persona_store -->|"contains"| node_persona_nuance
node_persona_store -->|"contains"| node_persona_accounts
node_agent_specs -->|"defines"| node_profiler_agent
node_agent_specs -->|"defines"| node_trendsetter_agent
node_agent_specs -->|"defines"| node_writer_agent
node_agent_specs -->|"defines"| node_follower_agent
node_agent_specs -->|"defines"| node_admin_agent
node_skills_library -->|"includes"| node_interview_skill
node_skills_library -->|"includes"| node_content_skill
node_skills_library -->|"includes"| node_qa_skill
node_skills_library -->|"includes"| node_publish_skill
node_host_hooks -->|"orchestrates"| node_agent_specs
node_claude_plugin -->|"loads"| node_host_hooks
node_codex_sync -->|"syncs"| node_skills_library
node_server_api -->|"uses"| node_ploon_domain
node_dashboard -->|"calls"| node_server_api
node_server_api -->|"reads"| node_persona_store
node_server_api -->|"reads writes"| node_content_pipeline
node_content_pipeline -->|"feeds"| node_trend_inputs
node_content_pipeline -->|"creates"| node_drafts
node_content_pipeline -->|"routes to"| node_qa_outputs
node_content_pipeline -->|"lands in"| node_published_content
node_dashboard -->|"visualizes"| node_content_pipeline
node_dashboard -->|"monitors"| node_agent_specs
node_deck_assets -->|"supports"| node_dashboard

click node_persona_store "https://github.com/lilmgenius/polysona/tree/main/personas/default"
click node_persona_core "https://github.com/lilmgenius/polysona/blob/main/personas/default/persona.md"
click node_persona_nuance "https://github.com/lilmgenius/polysona/blob/main/personas/default/nuance.md"
click node_persona_accounts "https://github.com/lilmgenius/polysona/blob/main/personas/default/accounts.md"
click node_agent_specs "https://github.com/lilmgenius/polysona/tree/main/agents"
click node_profiler_agent "https://github.com/lilmgenius/polysona/blob/main/agents/profiler.md"
click node_trendsetter_agent "https://github.com/lilmgenius/polysona/blob/main/agents/trendsetter.md"
click node_writer_agent "https://github.com/lilmgenius/polysona/blob/main/agents/content-writer.md"
click node_follower_agent "https://github.com/lilmgenius/polysona/blob/main/agents/virtual-follower.md"
click node_admin_agent "https://github.com/lilmgenius/polysona/blob/main/agents/admin.md"
click node_skills_library "https://github.com/lilmgenius/polysona/tree/main/skills"
click node_interview_skill "https://github.com/lilmgenius/polysona/blob/main/skills/interview/SKILL.md"
click node_content_skill "https://github.com/lilmgenius/polysona/blob/main/skills/content/SKILL.md"
click node_qa_skill "https://github.com/lilmgenius/polysona/blob/main/skills/qa/SKILL.md"
click node_publish_skill "https://github.com/lilmgenius/polysona/blob/main/skills/publish/SKILL.md"
click node_dashboard "https://github.com/lilmgenius/polysona/tree/main/client"
click node_server_api "https://github.com/lilmgenius/polysona/tree/main/server"
click node_ploon_domain "https://github.com/lilmgenius/polysona/blob/main/server/lib/ploon.ts"
click node_content_pipeline "https://github.com/lilmgenius/polysona/tree/main/content"
click node_drafts "https://github.com/lilmgenius/polysona/tree/main/content/drafts"
click node_qa_outputs "https://github.com/lilmgenius/polysona/tree/main/content/qa"
click node_published_content "https://github.com/lilmgenius/polysona/tree/main/content/published"
click node_trend_inputs "https://github.com/lilmgenius/polysona/tree/main/content/trends"
click node_deck_assets "https://github.com/lilmgenius/polysona/tree/main/decks"
click node_host_hooks "https://github.com/lilmgenius/polysona/tree/main/hooks"
click node_claude_plugin "https://github.com/lilmgenius/polysona/blob/main/.claude-plugin"
click node_codex_sync "https://github.com/lilmgenius/polysona/blob/main/scripts/sync-codex-skills.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_host_hooks,node_claude_plugin,node_codex_sync toneBlue
class node_persona_store,node_persona_core,node_persona_nuance,node_persona_accounts,node_agent_specs,node_profiler_agent,node_trendsetter_agent,node_writer_agent,node_follower_agent,node_admin_agent,node_skills_library,node_interview_skill,node_content_skill,node_qa_skill,node_publish_skill toneAmber
class node_dashboard,node_server_api,node_ploon_domain toneMint
class node_content_pipeline,node_drafts,node_qa_outputs,node_published_content,node_trend_inputs,node_deck_assets toneRose
```

## Components

### Host integration

Runtime-specific wiring for Codex and Claude Code, plus lifecycle hooks and skill syncing.

- [Hooks](https://github.com/lilmgenius/polysona/tree/main/hooks): runtime hooks · Lifecycle hooks that shape agent behavior in supported hosts. · `hooks`
- [Claude plugin](https://github.com/lilmgenius/polysona/blob/main/.claude-plugin): claude config · Claude Code plugin and marketplace metadata. · `.claude-plugin`
- [Codex sync](https://github.com/lilmgenius/polysona/blob/main/scripts/sync-codex-skills.mjs): sync script · Mirrors skills into Codex-compatible layout. · `scripts/sync-codex-skills.mjs`

### Persona and agents

Persistent persona state, agent role definitions, and reusable skill instructions.

- [Persona store](https://github.com/lilmgenius/polysona/tree/main/personas/default): markdown state · Default persona files used as the durable input for the workflow. · `personas/default`
- [Core persona](https://github.com/lilmgenius/polysona/blob/main/personas/default/persona.md): persona file · Primary persona profile consumed by downstream agents. · `personas/default/persona.md`
- [Nuance notes](https://github.com/lilmgenius/polysona/blob/main/personas/default/nuance.md): persona file · Secondary tone and subtle-trait context for the persona. · `personas/default/nuance.md`
- [Account context](https://github.com/lilmgenius/polysona/blob/main/personas/default/accounts.md): persona file · Platform and account context for persona-specific operations. · `personas/default/accounts.md`
- [Agent specs](https://github.com/lilmgenius/polysona/tree/main/agents): agent definitions · Role-specific agent prompts and behavior definitions. · `agents`
- [Profiler](https://github.com/lilmgenius/polysona/blob/main/agents/profiler.md): agent role · Interviews and extracts persona signals. · `agents/profiler.md`
- [Trendsetter](https://github.com/lilmgenius/polysona/blob/main/agents/trendsetter.md): agent role · Collects trend topics for content planning. · `agents/trendsetter.md`
- [Content writer](https://github.com/lilmgenius/polysona/blob/main/agents/content-writer.md): agent role · Generates platform-specific drafts from persona and trend inputs. · `agents/content-writer.md`
- [Virtual follower](https://github.com/lilmgenius/polysona/blob/main/agents/virtual-follower.md): agent role · Simulates audience QA and ranks content quality. · `agents/virtual-follower.md`
- [Admin](https://github.com/lilmgenius/polysona/blob/main/agents/admin.md): agent role · Handles publish and tracking steps. · `agents/admin.md`
- [Skills library](https://github.com/lilmgenius/polysona/tree/main/skills): skill pack · Portable command-oriented instructions shared across runtimes. · `skills`
- [Interview](https://github.com/lilmgenius/polysona/blob/main/skills/interview/SKILL.md): skill · Guides persona extraction interviews. · `skills/interview/SKILL.md`
- [Content](https://github.com/lilmgenius/polysona/blob/main/skills/content/SKILL.md): skill · Guides content generation workflows. · `skills/content/SKILL.md`
- [QA](https://github.com/lilmgenius/polysona/blob/main/skills/qa/SKILL.md): skill · Guides simulated audience review and critique. · `skills/qa/SKILL.md`
- [Publish](https://github.com/lilmgenius/polysona/blob/main/skills/publish/SKILL.md): skill · Guides publication and tracking steps. · `skills/publish/SKILL.md`

### Workspace runtime

Local API and dashboard that inspect and coordinate the filesystem-backed workflow.

- [Dashboard](https://github.com/lilmgenius/polysona/tree/main/client): vite react ui · Local observability UI for personas, agents, and content flow. · `client`
- [API server](https://github.com/lilmgenius/polysona/tree/main/server): ts backend · Backend bridge between the dashboard and filesystem-backed workspace state. · `server`
- [Ploon logic](https://github.com/lilmgenius/polysona/blob/main/server/lib/ploon.ts): server domain · Shared server-side workspace logic. · `server/lib/ploon.ts`

### Artifacts

Generated drafts, QA outputs, published content, and presentation assets.

- [Content pipeline](https://github.com/lilmgenius/polysona/tree/main/content): artifact flow · Filesystem-backed lifecycle for drafts, QA, trends, and published outputs. · `content`
- [Drafts](https://github.com/lilmgenius/polysona/tree/main/content/drafts): content stage · Generated content drafts awaiting review. · `content/drafts`
- [QA outputs](https://github.com/lilmgenius/polysona/tree/main/content/qa): content stage · Review artifacts produced by the virtual follower stage. · `content/qa`
- [Published](https://github.com/lilmgenius/polysona/tree/main/content/published): content stage · Final published content artifacts. · `content/published`
- [Trends](https://github.com/lilmgenius/polysona/tree/main/content/trends): content stage · Collected trend signals used to seed content generation. · `content/trends`
- [Decks](https://github.com/lilmgenius/polysona/tree/main/decks): presentation assets · Static slide decks and viewers for demos or presentations. · `decks`

## Connections

- Persona store → Core persona: contains · The persona store is materialized as markdown files.
- Persona store → Nuance notes: contains · Nuance is stored alongside the core persona.
- Persona store → Account context: contains · Account context lives in the same durable store.
- Agent specs → Profiler: defines · Agent files declare distinct responsibilities.
- Agent specs → Trendsetter: defines · Trend collection is a separate role.
- Agent specs → Content writer: defines · Draft generation is isolated as its own role.
- Agent specs → Virtual follower: defines · QA is modeled as a simulated audience agent.
- Agent specs → Admin: defines · Publishing and tracking are handled separately.
- Skills library → Interview: includes · Interview instructions are one of the portable skills.
- Skills library → Content: includes · Content generation instructions are packaged as a skill.
- Skills library → QA: includes · Quality review behavior is defined as a skill.
- Skills library → Publish: includes · Publication workflow is exposed as a skill.
- Hooks → Agent specs: orchestrates · Lifecycle hooks can steer agent execution in host environments.
- Claude plugin → Hooks: loads · Claude Code integration uses plugin metadata and hooks.
- Codex sync → Skills library: syncs · Skill definitions are mirrored for Codex runtime consumption.
- API server → Ploon logic: uses · API routes rely on shared server-side domain logic.
- Dashboard → API server: calls · The UI talks to the backend for workspace state and actions.
- API server → Persona store: reads · Backend surfaces persona state to the dashboard.
- API server → Content pipeline: reads writes · Backend bridges filesystem content stages.
- Content pipeline → Trends: feeds · Trend discovery seeds the content workflow.
- Content pipeline → Drafts: creates · Drafts are generated from persona and trend inputs.
- Content pipeline → QA outputs: routes to · QA artifacts are produced after follower review.
- Content pipeline → Published: lands in · Approved content is published into the final stage.
- Dashboard → Content pipeline: visualizes · The dashboard emphasizes pipeline visibility and inspection.
- Dashboard → Agent specs: monitors · Agent status and behavior are observable in the UI.
- Decks → Dashboard: supports · Presentation assets complement the local product story.
