# sharqiewicz/numora architecture

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

- Interactive diagram: https://gitdiagram.com/sharqiewicz/numora
- Repository: https://github.com/sharqiewicz/numora

## Overview

##### Project’s type and purpose
- The project is a lightweight, framework-agnostic numeric input library, focused on handling financial/DeFi numeric inputs.
- Its core functionality is encapsulated in the "packages/core" directory, while the "docs" directory contains a demo/documentation site built using modern web tooling (Svelte, Astro, etc.).
- The library is implemented in TypeScript and is designed to be pluggable with any front-end framework (with adapters for React, Vue, and Svelte in progress or provided).

##### Main components from the file tree
- Root Level:
- Configuration files like package.json and .gitignore that provide the project’s settings.
- Documentation Site (docs):
- Contains its own package.json, configuration files (astro.config.mjs, svelte.config.js, tsconfig.json), and source code under docs/src.
- The docs/src directory holds assets, Svelte components (e.g., NumoraDemo.svelte), and markdown/mdx content that describes usage and guides.
- Core Package (packages/core):
- Contains the source code under packages/core/src, including the main NumericInput implementation (NumericInput.ts) and various helper utilities.
- There is also a test suite in packages/core/tests to ensure functionality, plus relevant build and configuration files (vite.config.ts, tsconfig.json).
- Utilities & Testing:
- The utilities for decimals, event handling, and input sanitization indicate the presence of discrete logic layers.

##### Core points
a. Main Components:
- Numora Core Library: Show this as the central component, containing modules such as:
- NumericInput module (primary API for numeric input handling)
- Utils modules (decimals, event-handlers, sanitization)
- Test suite (ensuring correctness)
- Demo/Documentation Site: Represented as a separate module that utilizes the core library. It includes:
- Documentation pages (guides, getting started, examples)
- Svelte components (e.g., NumoraDemo.svelte) that demonstrate usage.
- Build/Configuration Infrastructure: Consider including configuration files (e.g., tsconfig.json, vite.config.ts, astro.config.mjs) to indicate how the project is built and integrated.

b. Relationships and Interactions:
- The Core Library provides utilities and events that can be consumed by any framework adapter. You might highlight potential integration points for the future adapters (React, Vue, etc.) as extensions of the core library.
- The test suite interacts with the core modules to validate functionality. Indicate a connection between the Core Library and its Tests.

c. Architectural Patterns & Design Principles:
- Modular Design: The separation between core functionality (in packages/core) and the demo/documentation (in docs) clearly shows modularity.
- Separation of Concerns: Core logic (input validation, sanitization, event handling) is isolated from the presentation layer.
- Framework Agnosticism: Emphasize that the library’s design does not tie it to a specific frontend framework.

d. Relevant Technologies:
- TypeScript: Core language used for creating a strongly typed API.
- Svelte (and possibly Astro): For the demo and documentation site.
- Testing Framework (evident from files in packages/core/tests): To cover unit testing.
- Build Tools: Vite for bundling (vite.config.ts), and project configurations like tsconfig.json.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Numora Core Library
    subgraph "Numora Core Library"
        NCI["NumericInput Module"]:::core
        UTILS["Utility Modules"]:::core
    end

    %% Build & Configuration for Core
    subgraph "Build & Configuration (Core)"
        VITE["Core Vite Config"]:::config
        TSC["Core TSConfig"]:::config
    end

    %% Documentation / Demo Site
    subgraph "Documentation / Demo Site"
        DOC["Documentation & Demo Site"]:::docs
        DEMO["Svelte Demo Component"]:::docs
        CONTENT["Content & Guides"]:::docs
    end

    %% Build & Configuration for Documentation
    subgraph "Build & Configuration (Documentation)"
        ASTRO["Docs Astro Config"]:::config
        SVELTE["Docs Svelte Config"]:::config
        DOC_TSC["Docs TSConfig"]:::config
    end

    %% Core Test Suite
    TST["Core Test Suite"]:::tests

    %% Relationships
    NCI -->|"uses-utils"| UTILS
    DOC -->|"leverages"| NCI
    DEMO -->|"demonstrates"| NCI
    TST -->|"tests"| NCI
    VITE -.->|"build-config"| NCI
    TSC -.->|"build-config"| NCI
    ASTRO -.->|"supports"| DOC
    SVELTE -.->|"supports"| DOC
    DOC_TSC -.->|"supports"| DOC

    %% Click Events
    click NCI "https://github.com/sharqiewicz/numora/blob/main/packages/core/src/NumericInput.ts"
    click UTILS "https://github.com/sharqiewicz/numora/tree/main/packages/core/src/utils"
    click TST "https://github.com/sharqiewicz/numora/blob/main/packages/core/tests/NumericInput.test.ts"
    click DOC "https://github.com/sharqiewicz/numora/tree/main/docs"
    click DEMO "https://github.com/sharqiewicz/numora/blob/main/docs/src/components/NumoraDemo.svelte"
    click CONTENT "https://github.com/sharqiewicz/numora/tree/main/docs/src/content"
    click VITE "https://github.com/sharqiewicz/numora/blob/main/packages/core/vite.config.ts"
    click TSC "https://github.com/sharqiewicz/numora/blob/main/packages/core/tsconfig.json"
    click ASTRO "https://github.com/sharqiewicz/numora/blob/main/docs/astro.config.mjs"
    click SVELTE "https://github.com/sharqiewicz/numora/blob/main/docs/svelte.config.js"
    click DOC_TSC "https://github.com/sharqiewicz/numora/blob/main/docs/tsconfig.json"

    %% Styles
    classDef core fill:#a0d8f1,stroke:#034f84,stroke-width:2px;
    classDef docs fill:#f9d5e5,stroke:#ad1457,stroke-width:2px;
    classDef tests fill:#d0e6a5,stroke:#558b2f,stroke-width:2px;
    classDef config fill:#ffe0b2,stroke:#f57c00,stroke-width:2px;
```
