# helloprkr/knowledgebase architecture

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

- Interactive diagram: https://gitdiagram.com/helloprkr/knowledgebase
- Repository: https://github.com/helloprkr/knowledgebase

## Overview

##### Project Type and Purpose
- Base is a Linux-daemon + CLI tool for continuous activity monitoring and querying.
- It captures low-level events (keystrokes, mouse clicks, window focus), stores them in a local database (SQLite + daily Parquet), and exposes a query interface (selfstats/Baseview) that uses DuckDB for analytics.

##### High-Level Architectural Components
a. OS Event Sources
- Keyboard events
- Mouse events
- Window manager (focus/title) events
b. Sniffer Module (sniff_x.py)
- Listens to OS event streams
- Emits normalized activity records
c. Activity Store (activity_store.py)
- Receives events from sniffer
- Writes to SQLite in real time
- Rolls up each day’s data into Parquet files
d. Database Layer
- SQLite: live ingestion, metadata
- Parquet files: archived daily data
- DuckDB: query engine that federates SQLite + Parquet
e. Models & Query Layer (models.py + stats.py)
- Defines table schemas and ORM-like access
- Implements CLI commands (Baseview/selfstats)
- Parses user filters, builds DuckDB queries
f. Configuration (config.py)
- Loads defaults, overrides from CLI or config file
g. CLI Entrypoints
- Base (daemon launcher)
- Baseview/selfstats (analytics interface)
h. External Integrations (future/optional)
- Model API for natural-language queries
- cron/sendEmail for scheduled reports

##### Relationships and Data Flows
- OS Events → Sniffer → Activity Store → SQLite (real-time)
- Activity Store → Parquet (daily batch)
- CLI (“selfstats”) → Models → DuckDB → (SQLite + Parquet) → Output
- Config is consulted by both Daemon and CLI at startup
- Optional: Cron → selfstats → sendEmail

##### Architectural Patterns and Principles
- Separation of concerns: sniffing vs. storage vs. querying
- Batch vs. stream: real-time writes in SQLite, daily dumps to Parquet
- Adapter pattern: Models layer adapts DuckDB/SQLite/Parquet to a uniform API
- CLI-driven: no web UI, lightweight Python package, Unix philosophy

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    subgraph "Data Sources"
        direction TB
        OS["OS Events\n(Keyboard, Mouse, Window)"]:::external
    end

    %% Ingestion & Storage
    subgraph "Ingestion & Storage"
        direction TB
        Daemon(["Base Daemon"]):::process
        ConfigLoader["config.py"]:::config
        Sniffer["sniff_x"]:::ingestion
        ActivityStore["activity_store"]:::ingestion
        Period["period.py\n(Daily Roll‐up)"]:::ingestion
        SQLite[(SQLite DB)]:::storage
        Parquet[(Parquet Files)]:::storage
    end

    %% Analytics & Querying
    subgraph "Analytics & Querying"
        direction TB
        CLI(["selfstats / Baseview CLI"]):::process
        Models["models.py"]:::query
        Stats["stats.py"]:::query
        DuckDB[(DuckDB Engine)]:::query
    end

    %% External / Cron
    subgraph "External Integrations"
        direction TB
        Cron(["Cron Scheduler"]):::external
        SendEmail(["sendEmail"]):::external
        ModelAPI(["Model API\n(NL Queries)"]):::planned
    end

    %% Project Metadata
    subgraph "Project Metadata"
        direction TB
        Init["__init__.py"]:::meta
        Setup["setup.py"]:::meta
        Req["requirements.txt"]:::meta
        Readme["README.md"]:::meta
        Makefile["Makefile"]:::meta
    end

    %% Connections
    OS -->|"EventRecord"| Sniffer
    Daemon -->|uses Config| ConfigLoader
    Daemon -->|spawns| Sniffer
    Sniffer -->|"EventRecord"| ActivityStore
    ActivityStore -->|"SQL INSERT (real-time)"| SQLite
    ActivityStore -->|"Parquet write\n(daily batch)"| Parquet
    ActivityStore -->|uses| Period

    CLI -->|uses Config| ConfigLoader
    CLI -->|CLI args| Stats
    Stats -->|calls schema| Models
    Models -->|builds query| DuckDB
    DuckDB -->|"loads via SQLite"| SQLite
    DuckDB -->|"loads via Parquet"| Parquet

    Cron -->|triggers| CLI
    CLI -->|outputs report| SendEmail
    Cron -->|optional future| ModelAPI

    %% Click Events
    click Sniffer "https://github.com/helloprkr/knowledgebase/blob/main/Base/sniff_x.py"
    click ActivityStore "https://github.com/helloprkr/knowledgebase/blob/main/Base/activity_store.py"
    click ConfigLoader "https://github.com/helloprkr/knowledgebase/blob/main/Base/config.py"
    click Models "https://github.com/helloprkr/knowledgebase/blob/main/Base/models.py"
    click Stats "https://github.com/helloprkr/knowledgebase/blob/main/Base/stats.py"
    click Period "https://github.com/helloprkr/knowledgebase/blob/main/Base/period.py"
    click Init "https://github.com/helloprkr/knowledgebase/blob/main/Base/__init__.py"
    click Setup "https://github.com/helloprkr/knowledgebase/blob/main/setup.py"
    click Req "https://github.com/helloprkr/knowledgebase/blob/main/requirements.txt"
    click Readme "https://github.com/helloprkr/knowledgebase/blob/main/README.md"
    click Makefile "https://github.com/helloprkr/knowledgebase/tree/main/Makefile"

    %% Styles
    classDef ingestion fill:#e0ffe0,stroke:#2d8f2d
    classDef storage fill:#e0e0ff,stroke:#2d2d8f
    classDef query fill:#ffe0b3,stroke:#d98f00
    classDef external fill:#f0f0f0,stroke:#888888
    classDef planned stroke-dasharray: 5 5,fill:#ffffff,stroke:#888888
    classDef process fill:#ffffff,stroke:#333333,stroke-width:2px
    classDef config fill:#fff0e6,stroke:#ff9900
    classDef meta fill:#f9f9f9,stroke:#999999,stroke-dasharray: 2 2
```
