# yoheinakajima/pippin architecture

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

- Interactive diagram: https://gitdiagram.com/yoheinakajima/pippin
- Repository: https://github.com/yoheinakajima/pippin

## Overview

##### Main Components

a) Core Framework Layer:
- Activity Management System
- State Management System
- Memory System
- Web Server
- Main Loop Controller

b) External Integration Layer:
- OpenAI API Integration
- Twitter API Integration
- WebSocket Connection

c) Storage Layer:
- SQLite Database (memory.db)
- File System (for images/static content)

**[Client Layer]**
- ↑↓
**[Web Server Layer]**
- ↑↓
**[Core Processing Layer]**
- ↑↓
**[Storage Layer]**

##### Component Details

a) Client Layer:
- WebSocket connection for real-time updates
- Static asset serving (CSS, JS, images)

b) Web Server Layer:
- Flask server component (framework/server.py)
- WebSocket handler
- Route handlers for dashboard and logs

c) Core Processing Layer (Most Complex):

##### Activity System
- Activity Loader
- Activity Selector
- Activity Constraints Handler
- Individual Activities (show as grouped components)

##### State Management
- State Variables (energy, happiness, XP)
- State Update Handlers

##### Memory System
- Memory Storage Manager
- Embedding Generator
- Memory Query Engine

d) Storage Layer:
- SQLite Database
- File System Storage

##### Specific Implementation Details

Processes like:
##### Activity Selection Flow
**Activity Selector → State Check → Constraint Check → Probability Calculation → Activity Execution**

##### Memory Operation Flow
**Activity → Memory Storage → Embedding Generation → Database Storage**

##### Real-time Update Flow
**Activity Updates → State Changes → WebSocket → Client Dashboard**

##### Additional Elements

Include:
- Version information
- External API dependencies
- Configuration requirements (YAML files)
- Key file locations

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        Browser["Web Browser"]
        Dashboard["Dashboard Interface"]
        LogsView["Logs View"]
    end

    subgraph WebServer
        Server["Flask Server"]:::server
        WSHandler["WebSocket Handler"]
        Routes["Route Handlers"]
        Static["Static Assets"]:::static
    end

    subgraph CoreProcessing
        MainLoop["Main Loop Controller"]:::main
        
        subgraph ActivitySystem
            ActLoader["Activity Loader"]:::activity
            ActSelector["Activity Selector"]:::activity
            ActConstraints["Constraints Handler"]:::activity
            Activities["Activities"]:::activity
        end
        
        subgraph StateSystem
            StateManager["State Manager"]:::state
            SharedData["Shared Data"]:::state
        end
        
        subgraph MemorySystem
            MemManager["Memory Manager"]:::memory
            EmbedGen["Embedding Generator"]:::memory
            MemQuery["Memory Query Engine"]:::memory
        end

        subgraph Skills
            DrawSkill["Draw Skill"]:::skill
            ImageGen["Image Generator"]:::skill
            GifSkill["GIF Skill"]:::skill
        end
    end

    subgraph ExternalIntegration
        OpenAI["OpenAI API"]:::external
        Twitter["Twitter API"]:::external
        IntegrationEndpoints["Integration Endpoints"]:::external
    end

    subgraph Storage
        DB[(SQLite Database)]:::storage
        FileSystem["File System"]:::storage
    end

    Browser --> Dashboard
    Browser --> LogsView
    Dashboard --> WSHandler
    LogsView --> Routes
    Routes --> Server
    WSHandler --> Server
    Static --> Server

    Server --> MainLoop
    MainLoop --> ActSelector
    ActSelector --> ActLoader
    ActLoader --> Activities
    ActConstraints --> ActSelector
    
    Activities --> StateManager
    Activities --> MemManager
    StateManager --> SharedData
    
    MemManager --> EmbedGen
    EmbedGen --> MemQuery
    MemQuery --> DB
    
    Activities --> Skills
    Skills --> FileSystem
    Skills --> OpenAI
    
    IntegrationEndpoints --> Twitter
    IntegrationEndpoints --> OpenAI

    %% Style Definitions
    classDef server fill:#9370DB
    classDef activity fill:#FFA500
    classDef state fill:#4169E1
    classDef memory fill:#20B2AA
    classDef storage fill:#FFD700
    classDef external fill:#98FB98
    classDef static fill:#DDA0DD
    classDef skill fill:#FF6347
    classDef main fill:#4682B4

    %% Click Events
    click Server "https://github.com/yoheinakajima/pippin/blob/main/framework/server.py"
    click Static "https://github.com/yoheinakajima/pippin/tree/main/static/"
    click MainLoop "https://github.com/yoheinakajima/pippin/blob/main/framework/main.py"
    click ActLoader "https://github.com/yoheinakajima/pippin/blob/main/framework/activity_loader.py"
    click ActSelector "https://github.com/yoheinakajima/pippin/blob/main/framework/activity_selector.py"
    click ActConstraints "https://github.com/yoheinakajima/pippin/blob/main/framework/activity_constraints.py"
    click Activities "https://github.com/yoheinakajima/pippin/tree/main/activities/"
    click StateManager "https://github.com/yoheinakajima/pippin/blob/main/framework/state.py"
    click SharedData "https://github.com/yoheinakajima/pippin/blob/main/framework/shared_data.py"
    click MemManager "https://github.com/yoheinakajima/pippin/blob/main/framework/memory.py"
    click DB "https://github.com/yoheinakajima/pippin/blob/main/memory.db"
    click DrawSkill "https://github.com/yoheinakajima/pippin/blob/main/skills/draw.py"
    click ImageGen "https://github.com/yoheinakajima/pippin/blob/main/skills/generate_pippin_image.py"
    click GifSkill "https://github.com/yoheinakajima/pippin/blob/main/skills/gif.py"
    click IntegrationEndpoints "https://github.com/yoheinakajima/pippin/blob/main/framework/integration_endpoints.py"
    click FileSystem "https://github.com/yoheinakajima/pippin/tree/main/static/images/"
```
