# onejs/one architecture

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

- Interactive diagram: https://gitdiagram.com/onejs/one
- Repository: https://github.com/onejs/one

## Overview

This project is a large, multipurpose monorepo designed for building “One” applications – a framework that unifies multiple aspects of app development (web, native, backend, and tooling). The project’s purpose is to offer a full-stack solution where a core set of packages (like the compiler, routing utilities, theming, and development tools) work together to provide a cohesive development experience for both production apps and experimental/demo apps. The README points to the documentation website (onestack.dev), confirming that the system is intended to be used as a complete toolkit for building modern applications.

##### Main Components
- Core Packages: Identify folders such as “packages/one”, “packages/compiler”, “packages/mdx”, “packages/react-native-prebuilt”, “packages/vxrn”, etc. These form the backbone of the framework and include modules for routing, code transformation, linking, utilities, and platform-specific adaptations.
- Examples: The “examples” directory contains multiple demo apps (e.g., one-basic, one-recommended, one-tailwind, one-zero, etc.) which help demonstrate different configurations and usage scenarios.
- Tests and CI/CD: The “tests” directory (with various subdirectories for hmr, sandbox, etc.) along with CI/CD configurations (GitHub workflows, Dockerfiles, etc.) highlight a robust testing and build process.
- External Tools & Configuration: Files like Dockerfile, .yarnrc.yml, and Vite config files show integrations with bundlers, native build tools (e.g., Tauri), and dependency managers.

##### Out Relationships and Interactions
- That testing, deployment, and CI/CD pipelines (GitHub workflows, Docker, and scripts in “scripts” and “tests”) surveil the entire system to ensure consistency.

##### Architectural Patterns and Design Principles
- Modularity: The monorepo is broken into many discrete packages—each with a very specific role. This separation allows individual modules to be developed, tested, and deployed independently.
- Full-stack integration: The architecture clearly separates concerns between frontend (React components, routing, theming), business logic (core routing, middleware, CLI tools), and build/deployment pipelines.
- Cross-platform support: There are components for web, native (React Native, Tauri), and SSR (server rendering) processes.
- Extensibility and flexibility: Several “create” and “debug” packages (for instance, “packages/create-vxrn” and “packages/debug”) enable developers to scaffold and troubleshoot projects using this unified framework.

##### Relevant Technologies and Toolings
- Bundlers and Build Tools: Vite (vite.config.ts files), Webpack integrations, as well as specific plugins in the “packages/one/src/vite/plugins”.
- Code Transformation: Compiler packages using Babel and SWC for code transformation.
- Testing Frameworks: Presence of tests and configuration for Vitest (for example, vitest.config.ts files in various directories).
- Native Build Integrations: Tauri configuration (in apps/devtools/src-tauri) and react-native configurations signal cross-platform development.
- Versioning and Dependency Management: Yarn usage, Docker configurations, and GitHub CI details.

- Clear Labels: Each node (e.g., “Core Packages,” “Compiler,” “App: devtools,” “Example: one-basic”) should be clearly labeled.
- Integration Points: Include nodes for external systems (CI/CD, native build engines, dependency managers) and highlight where configuration (Dockerfile, GitHub workflows) ties into the overall system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Monorepo Umbrella"]:::monorepo

    subgraph "Source & Core Build Pipeline"
        I["Source Code"]:::internal
        B2["Core Package – Compiler"]:::package
        B5["Core Package – VXRN (Build & Transformation Pipeline)"]:::package
    end

    subgraph "Core Packages"
        B1["Core Package – One Framework"]:::package
        B3["Core Package – MDX Utilities"]:::package
        B4["Core Package – React Native Prebuilt"]:::package
        B6["Core Package – Create VXRN (Scaffolding Tool)"]:::package
        B7["Core Package – Debug Tools"]:::package
    end

    subgraph "Applications"
        C["Devtools App"]:::app
        D["onestack.dev App"]:::app
        E["Repro App"]:::app
    end

    subgraph "Examples"
        F["Examples (Demo Apps)"]:::example
    end

    subgraph "Testing & CI/CD"
        G1["Tests Directory"]:::test
        G2["CI/CD & Workflow Configurations"]:::test
    end

    subgraph "External Tools & Configurations"
        H["External Tools & Configurations"]:::external
    end

    A -->|"contains"| I

    I -->|"transformation"| B2
    I -->|"bundling"| B5

    B2 -->|"transpiles"| C
    B2 -->|"transpiles"| D
    B2 -->|"transpiles"| E

    B5 -->|"bundles"| C
    B5 -->|"bundles"| D

    C -->|"imports"| B1
    D -->|"imports"| B1
    E -->|"imports"| B1

    F -->|"demo_of"| B1
    F -->|"demo_of"| B2

    H -->|"configures"| C
    H -->|"configures"| D

    G1 -->|"monitors"| A
    G2 -->|"deploys"| A

    class A monorepo
    class B1,B2,B3,B4,B5,B6,B7 package
    class C,D,E app
    class F example
    class G1,G2 test
    class H external
    class I internal

click A "https://github.com/onejs/one/blob/main/."
click B1 "https://github.com/onejs/one/tree/main/packages/one"
click B2 "https://github.com/onejs/one/tree/main/packages/compiler"
click B3 "https://github.com/onejs/one/tree/main/packages/mdx"
click B4 "https://github.com/onejs/one/tree/main/packages/react-native-prebuilt"
click B5 "https://github.com/onejs/one/tree/main/packages/vxrn"
click B6 "https://github.com/onejs/one/tree/main/packages/create-vxrn"
click B7 "https://github.com/onejs/one/tree/main/packages/debug"
click C "https://github.com/onejs/one/tree/main/apps/devtools"
click D "https://github.com/onejs/one/blob/main/apps/onestack.dev"
click E "https://github.com/onejs/one/tree/main/repro"
click F "https://github.com/onejs/one/tree/main/examples"
click G1 "https://github.com/onejs/one/tree/main/tests"
click G2 "https://github.com/onejs/one/tree/main/.github/workflows"
click H "https://github.com/onejs/one/blob/main/apps/devtools/vite.config.ts"
```
