# ostis-apps/nika architecture

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

- Interactive diagram: https://gitdiagram.com/ostis-apps/nika
- Repository: https://github.com/ostis-apps/nika

## Overview

##### Project Type and Purpose
- NIKA is a full-stack, containerized, knowledge-driven assistant built on OSTIS technology.
- It comprises a semantic knowledge engine (sc-machine), a set of problem-solver modules (C++ and Python), two web UIs (a React-based chat interface and SC-web), and a large on-disk knowledge base.

##### File Structure
- Top-level: Docker Compose, CMake, Conan, mkdocs, GitHub CI, scripts.
- interface/: React/TypeScript chat UI, served by webpack (dev server + custom wsServer).
- problem-solver/:
- py/: Python alternative implementation for message processing + WeatherAgent.
- knowledge-base/: thousands of .scs/.gwf files defining ontologies, patterns, agents.
- scripts/: entrypoints, healthchecks, build helpers.
- docker-compose.yml: orchestrates containers (sc-machine, problem-solver, interface, sc-web, etc.).

##### Extract Key Insights from README
- Two web UIs exposed:
- sc-web at localhost:8000
- dialogue chat UI at localhost:3033
- Knowledge base is rebuilt on container start (controlled via REBUILD_KB env).
- Communication: frontends ←→ backends via HTTP/WebSocket; problem-solver ←→ sc-machine via sc_http; message classification uses external Wit.ai.

##### Main Components and Their Interactions
a. Frontend Components
- React Chat UI (“interface” container): serves SPA, connects via WebSocket to problem-solver server.
b. Backend Components
- sc-machine container: core semantic engine, loads knowledge base and C++ modules as plugins, exposes sc_http REST API.
- problem-solver container:
- C++ plugins linked into sc-machine perform semantic reasoning tasks.
- Python server (optional) for lightweight module implementations.
- A WS/HTTP server (interface/scripts/wsServer.js and server.js) relays chat messages between React UI and sc-machine modules.
- External Service: Wit.ai (via MessageClassificationModule client) used by classification agent.
c. Data Stores and Assets
- knowledge-base directory: loaded into sc-machine memory at build time.
- Persistent storage for sc-machine (if configured) or in-memory.
- config files (.ini, .env) control container behavior.

##### Architectural Patterns and Design Principles
- Microservices: each major subsystem runs in its own Docker container.
- Plugin modularity: C++ modules compiled separately and loaded by sc-machine.
- Frontend/backend separation: React UI and SC-web are independent UIs.
- Semantic dataflow: Messages are transformed into semantic representations (.scs/.gwf), processed by logic rules and agents, then converted back to natural language.
- CI/CD: GitHub workflows for style checks, building, testing (Conan, CMake, pytest).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    subgraph "User Layer"
        Browser["Browser"]:::external
        ChatUI["React Chat UI (port 3033)"]:::frontend
        SCwebUI["SC-web UI (port 8000)"]:::frontend
    end

    Browser -->|"HTTP/WebSocket"| ChatUI
    Browser -->|"HTTP"| SCwebUI

    %% Application Layer
    subgraph "Application Layer"
        WSHTTP["WS/HTTP Gateway"]:::gateway
        ProblemSolver["Problem-Solver Server"]:::backend
        SCMachine["sc-machine"]:::backend
    end

    ChatUI -->|"WebSocket"| WSHTTP
    WSHTTP -->|"forward chat msg"| ProblemSolver
    ProblemSolver -->|"sc_http REST"| SCMachine
    SCMachine -->|"sc_http REST"| ProblemSolver
    ProblemSolver -->|"relay response"| WSHTTP
    WSHTTP -->|"WebSocket"| ChatUI

    %% sc-machine Plugins
    subgraph "sc-machine Plugins"
        DialogControl["Dialog Control Module"]:::plugin
        MsgClassification["Message Classification Module"]:::plugin
        MsgProcessing["Message Processing Module"]:::plugin
        MsgReply["Message Reply Module"]:::plugin
        NonAtomic["Non-Atomic Action Interpreter"]:::plugin
        InterfaceColor["Interface Color Agent"]:::plugin
        CommonUtils["Common Utilities & HTTP Client"]:::plugin
    end
    SCMachine --> DialogControl
    SCMachine --> MsgClassification
    SCMachine --> MsgProcessing
    SCMachine --> MsgReply
    SCMachine --> NonAtomic
    SCMachine --> InterfaceColor
    SCMachine --> CommonUtils

    %% Python Problem Solver
    subgraph "Python Problem-Solver"
        PyServer["Python Server"]:::python
        PyMsgProc["MessageProcessingModule.py"]:::python
        WeatherAgent["WeatherAgent.py"]:::python
    end
    ProblemSolver --> PyServer
    PyServer --> PyMsgProc
    PyServer --> WeatherAgent

    %% Knowledge Layer
    subgraph "Knowledge Layer"
        KB["Knowledge Base (.scs/.gwf files)"]:::database
    end
    KB -->|"mounted volume"| SCMachine

    %% External Services
    subgraph "External Services"
        WitAI["Wit.ai"]:::external
    end
    MsgClassification -->|"REST"| WitAI

    %% Configurations
    subgraph "Configuration & CI"
        DockerCfg["Docker Compose & Dockerfile"]:::config
        CI["GitHub Actions & CMake/Conan"]:::config
    end
    DockerCfg --> SCMachine
    DockerCfg --> ProblemSolver
    DockerCfg --> ChatUI
    DockerCfg --> SCwebUI
    CI --> SCMachine
    CI --> ProblemSolver

    %% Click Events
    click ChatUI "https://github.com/ostis-apps/nika/tree/main/interface/"
    click SCwebUI "https://github.com/ostis-apps/nika/tree/main/sc-web/"
    click WSHTTP "https://github.com/ostis-apps/nika/blob/main/interface/scripts/wsServer.js"
    click WSHTTP "https://github.com/ostis-apps/nika/blob/main/interface/server/server.js"
    click SCMachine "https://github.com/ostis-apps/nika/blob/main/docker-compose.yml"
    click SCMachine "https://github.com/ostis-apps/nika/tree/main/Dockerfile"
    click KB "https://github.com/ostis-apps/nika/tree/main/knowledge-base/"
    click DialogControl "https://github.com/ostis-apps/nika/tree/main/problem-solver/cxx/dialog-control-module/"
    click MsgClassification "https://github.com/ostis-apps/nika/tree/main/problem-solver/cxx/message-classification-module/"
    click MsgProcessing "https://github.com/ostis-apps/nika/tree/main/problem-solver/cxx/message-processing-module/"
    click MsgReply "https://github.com/ostis-apps/nika/tree/main/problem-solver/cxx/message-reply-module/"
    click NonAtomic "https://github.com/ostis-apps/nika/tree/main/problem-solver/cxx/non-atomic-action-interpreter-module/"
    click InterfaceColor "https://github.com/ostis-apps/nika/tree/main/problem-solver/cxx/interface-module/"
    click CommonUtils "https://github.com/ostis-apps/nika/tree/main/problem-solver/cxx/common-module/"
    click PyServer "https://github.com/ostis-apps/nika/blob/main/problem-solver/py/server.py"
    click PyMsgProc "https://github.com/ostis-apps/nika/blob/main/problem-solver/py/modules/messageProcessingModule/MessageProcessingModule.py"
    click WeatherAgent "https://github.com/ostis-apps/nika/blob/main/problem-solver/py/modules/WeatherAgent.py"
    click CI "https://github.com/ostis-apps/nika/tree/main/.github/workflows/"
    click CI "https://github.com/ostis-apps/nika/blob/main/CMakeLists.txt"
    click CI "https://github.com/ostis-apps/nika/blob/main/conanfile.py"
    click CI "https://github.com/ostis-apps/nika/tree/main/cmake/"
    click DockerCfg "https://github.com/ostis-apps/nika/blob/main/docker-compose.yml"
    click DockerCfg "https://github.com/ostis-apps/nika/tree/main/Dockerfile"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1;
    classDef backend fill:#F1F8E9,stroke:#AED581,color:#33691E;
    classDef gateway fill:#FFF3E0,stroke:#FFB74D,color:#E65100;
    classDef plugin fill:#F3E5F5,stroke:#BA68C8,color:#4A148C;
    classDef python fill:#EDE7F6,stroke:#9575CD,color:#311B92;
    classDef database fill:#E0F7FA,stroke:#4DD0E1,color:#006064;
    classDef external fill:#FFEBEE,stroke:#EF9A9A,color:#B71C1C;
    classDef config fill:#ECEFF1,stroke:#B0BEC5,color:#263238;
```
