Skip to content

kesler20/_devOS

BranchesTags

Repository files navigation

😼 devOS

Development Operating System

devOS is a development acceleration toolkit that combines visual design tools, code generation, Ralph-first automation, and version-controlled snippets to eliminate the gap between prototype and production code.

drawUML

TL;DR — devOS in 5 Minutes

Assumptions

  • You are inside an active git repository
  • You have Node.js installed
  • Your Python virtual environment is activated

Configure a Project

Point devOS at your project's directories and language once, then everything else (code gen, snippets, and automation utilities) reads from that config.

dev config

This writes specs/project_config.json with paths for DAOs, DTOs, routes, tests, and contract synchronization outputs.

Build Project Artefacts

Generate DAOs, DTOs, CRUD routes, and tests from your JSON specification:

dev build project_name               # full build — all artefacts for the named project
dev build dao project_name           # DAOs only
dev build dto project_name           # DTOs only
dev build api project_name           # API routes only
dev build tests api project_name     # API test scaffolding only
dev build tests services project_name # service test scaffolding only
dev build context .py,.md .          # aggregate project context file
dev sync                              # sync classes marked with @contract across Python/TypeScript

Launch the ORM Builder UI

Open the visual entity designer (drawORM) in your browser:

dev ui path,to,devOS

If this doesn't work, make sure you have Node.js installed and run npm install in the devOS/frontend directory.

Design entities, set field types and relationships, then export directly to specs/dao_spec.json.

Managing Credentials

Store per-project environment variables in the vault (outside of git):

vault/
  dotenv_project_name          # project-specific .env values
  dotenv_example_project_name  # template for new developers

Copy credentials from vault back into the current project (.env and .env.example):

dev get credentials project_name

Managing Secrets

Global secrets (not tied to any single project) live at the vault root:

vault/
  global_secret_{secret_key}

Set and retrieve global secrets:

dev set secrets secret_key secret_value
dev get secrets secret_key

Managing Snippets

Snippets are reusable code stored in a git-backed snippets repository. Pull/push snippets with explicit from/to paths:

dev get snippets
dev get snippet from python,sqlalchemy_adapter.py to path,to,local,sqlalchemy_adapter.py
dev set snippet from path,to,local,adapters.py to python,database-adapters,adapters.py

Categories include Python adapters, TypeScript components, GitHub Actions workflows, Dockerfiles, prompts, and Copilot instruction files.

Ralph-First Workflow

devOS now prioritizes a Ralph-first local workflow. Keep your AGENTS.md and ralph.sh files synchronized with prompt snippets using dev-sync.

Keeping devOS Up to Date

Add devOS_profile.ps1 to your PowerShell profile. It exposes a dev-update alias that pulls the latest changes, reinstalls the package into the currently activated environment, and returns you to your project directory:

# From your project directory (devOS lives one level up by default)
dev-update

# Specify a different devOS location or return directory
dev-update -DevOSPath "C:/path/to/devOS" -TargetDir "my-project"

Activate your environment before running dev-update — the script installs directly into whatever pip is on your PATH.

Fast Local Sync for AGENTS.md and ralph.sh

To keep local instruction files aligned with snippets in prompts/, add this function to your PowerShell profile (or to devOS_profile.ps1):

# A function that will run devOS to update specific files locally.
function Sync-devOS {
  param(
    [string]$Target = ""
  )

  switch ($Target.ToLower()) {
    "read_agents" {
      dev get snippet from prompts,AGENTS.md to AGENTS.md
    }
    "read_ralph" {
      dev get snippet from prompts,ralph.sh to ralph.sh
    }
    "write_agents" {
      dev set snippet from AGENTS.md to prompts,AGENTS.md
    }
    "write_ralph" {
      dev set snippet from ralph.sh to prompts,ralph.sh
    }
    default {
      Write-Host "Unknown target: $Target. Supported targets: read_agents, read_ralph, write_agents, write_ralph."
    }
  }
}
Set-Alias dev-sync Sync-devOS

Example usage:

# Pull down snippet updates
dev-sync read_agents
dev-sync read_ralph

# Push local edits back into snippets
dev-sync write_agents
dev-sync write_ralph

This gives you a quick read/write partition so you can edit locally, then sync back to devOS snippet storage immediately.

Table of Contents

Philosophy

The advent of LLMs means there's no excuse for not having tests, documentation, and high-quality clean code. devOS is built on these principles:

  1. Prototype first, refactor with design — Write messy code to understand the problem, then use devOS to rewrite it properly
  2. First version is always throwaway — Accept that prototypes are learning tools, not production artifacts
  3. Specifications over implementations — JSON specifications export to any language and avoid AST parsing errors
  4. Version-controlled development assets — Snippets, prompts, and configs live in git branches, not scattered files
  5. Ralph-first local workflows — Keep prompt and instruction files synced and runnable locally

devOS is not distributed via PyPI. It's meant to be cloned into each project where you can:

  • Customize default configs and settings for your team
  • Maintain your own snippets as git branches
  • Use it as a secrets vault
  • Run local Ralph workflows without cloud dependencies

Core Components

drawORM — Visual ORM Designer

A UI ORM builder powered by React Flow, inspired by drawSQL.

Purpose: Refactoring tool for data models

  • Design your domain entities visually
  • Generate DAOs, DTOs, CRUD routes, and tests automatically
  • Syncs specifications bidirectionally (like xstate, but for Clean Architecture)

drawUML — Specification Builder

A domain-specific visual language on top of JSON for defining:

  • Endpoints and schemas
  • Advanced behaviors (on-delete rules, data transformations, pre/post-instantiation hooks)
  • Business logic constraints

Why JSON specifications?

  • Easier to export to different programming languages
  • Less error-prone than building abstract syntax trees
  • Machine-readable for LLM code generation
  • Type-safe and version-controllable

Ralph Workflow Utilities

devOS provides utilities for keeping prompt and automation assets synced locally:

  • Sync AGENTS.md and ralph.sh with snippet storage
  • Reuse version-controlled prompts across projects
  • Keep workflows local-first for proprietary codebases

Installation

Prerequisites

  • Node.js v18 or above
  • Python 3.10 or above
  • An active git repository (devOS extracts repo name, tags, etc.)
  • (Optional) Tooling required by your local ralph.sh workflow

Setup

  1. Clone devOS into your project:
git clone https://github.com/kesler20/devOS.git
cd devOS
  1. Run the setup command:
dev setup

This will:

  • Install the ORM builder UI (React frontend)
  • Configure environment variables
  • Set up code snippets as git branches
  1. Configure your vault:

Store credentials and secrets outside of GitHub:

vault/
  dotenv_project_name
  dotenv_example_project_name
  global_secret_{secret_key}

Secrets are not project-specific and can be stored at the vault root level.

  1. Verify installation:
dev version

Key Concepts

Specification-Driven Development

devOS assumes you update DAOs and endpoints via specifications, freeing you to focus on:

  • Writing use cases
  • Implementing adapters (services)
  • Creating comprehensive tests

The Vault

A collection of credentials and secrets stored outside of GitHub that can be shared with team members.

Structure:

  • dotenv_project_name — Project-specific environment variables
  • dotenv_example_project_name — Example template for new developers
  • global_secret_{secret_key} — Non-project-specific secrets

Snippets as Version-Controlled Assets

Snippets are reusable code stored as git branches that can be pulled into any project:

  • Adapters, utils, and helpers
  • Prompts and AGENTS.md files
  • GitHub Actions workflows
  • Copilot instruction files
  • Dockerfiles and mocks

Philosophy: Clone devOS, update snippets in your own repo, and use it to speed up development across all your projects.

Configuration Paths

Paths are entered as comma-separated lists to remain platform-agnostic.

home_root configs:

  • Global configs using the user home directory as root
  • Paths start from ~ or $HOME

project_root configs:

  • Project-specific paths starting from the repository root
  • Define directories, filenames, and programming languages for generated code

ORM Builder UI Guidelines

  • Use array types to indicate one-to-many relationships
  • AI autocomplete is available in the editor for endpoint definitions
  • Visual design syncs bidirectionally with JSON specifications

Architecture

System Overview

graph TB
    subgraph "Visual Design Layer"
        A[drawORM UI]
        B[drawUML UI]
    end

    subgraph "Specification Layer"
        C[JSON Specifications]
        D[Domain-Specific Rules]
    end

    subgraph "Code Generation Layer"
        E[DAO Generator]
        F[DTO Generator]
        G[Route Generator]
        H[Test Generator]
        I[LLM Codegen]
    end

    subgraph "Local Workflow"
      J[Ralph Scripts]
      K[Prompt Snippets]
      L[Local Task Execution]
    end

    subgraph "Developer Assets"
        M[Snippets<br/>Git Branches]
        N[Vault<br/>Secrets]
        O[Templates]
    end

    A --> C
    B --> C
    C --> D
    D --> E
    D --> F
    D --> G
    D --> H
    D --> I
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
    J --> K
    K --> L
    M --> J
    N --> J
    O --> E
    O --> F
    O --> G
    O --> H
Loading

Data Flow

sequenceDiagram
    participant Dev as Developer
    participant UI as drawORM/drawUML
    participant Spec as JSON Specification
    participant Gen as Code Generator
    participant Ralph as Ralph Workflow
    participant Local as Local Task Runtime

    Dev->>UI: Design entities & endpoints
    UI->>Spec: Generate JSON specification
    Spec->>Gen: Parse and validate
    Gen->>Ralph: Create local generation task
    Ralph->>Local: Execute code generation
    Local->>Ralph: Apply templates & snippets
    Gen->>Dev: Produce DAOs, DTOs, routes, tests
    Dev->>Local: Review generated changes
Loading

Clean Architecture Layers

devOS enforces Clean Architecture principles through code generation:

┌─────────────────────────────────────────┐
│          Domain Layer                    │
│  • entities.py (DAOs)                   │
│  • Business rules & constraints         │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│        Use Cases Layer                   │
│  • crud_dto.py, custom_dto.py           │
│  • use_cases.py                         │
│  • ports.py (interfaces)                │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│      Infrastructure Layer                │
│  • crud_routes.py, custom_routes.py     │
│  • adapters.py                          │
│  • schema.py (external contracts)       │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│          Tests Layer                     │
│  • unit_tests.py                        │
│  • integration_tests.py                 │
└─────────────────────────────────────────┘

Dependency Rule: Inner layers never depend on outer layers.

Code Generation

Supported Languages

  • Python (FastAPI, SQLAlchemy, Pydantic)
  • TypeScript (React, Express, type definitions)
  • More languages via LLM codegen when not explicitly supported

Generation Workflow

  1. Design in drawORM/drawUML — Visually define entities, relationships, and endpoints
  2. Export JSON specification — Domain-specific rules encoded as JSON
  3. Run code generator:
dev build project_name               # Generate all artifacts
dev build dao project_name           # Generate DAOs only
dev build dto project_name           # Generate DTOs only
dev build api project_name           # Generate API routes only
dev build tests api project_name     # Generate API test scaffolding only
dev build tests services project_name # Generate service test scaffolding only
dev sync                              # Translate all classes in @contract files
  1. LLM Integration — When programming language is not specified, devOS invokes an LLM codegen workflow using AGENTS.md for architectural guidance

Test Generation

  • Service tests: Code generator searches for files with @service marker
  • API tests: Generates tests only for endpoints created by devOS code generator

Extending Generated Code

Generated code is importable and extensible:

# Import generated routes
from generated_endpoints import app

# Extend with custom routes
@app.route("/custom_endpoint", methods=["POST"])
def custom_endpoint():
    return {"message": "Custom logic here"}

Suggested Project Structure

project/
├── domain/
│   └── dao.py                    # Generated entities
├── use_cases/
│   ├── crud_dto.py               # Generated CRUD DTOs
│   ├── custom_dto.py             # Your custom DTOs
│   ├── use_cases.py              # Your business logic
│   ├── ports.py                  # Interfaces for adapters
│   └── utils/                    # Shared utilities
├── infrastructure/
│   ├── crud_routes.py            # Generated CRUD routes
│   ├── custom_routes.py          # Your custom routes
│   ├── adapters.py               # External service adapters
│   └── schema.py                 # Third-party contracts
└── tests/
    ├── unit_tests.py             # Generated unit tests
    └── integration_tests.py      # Generated integration tests

Software Design

React Component Architecture

The frontend is built with React + TypeScript following event-driven patterns outlined in AGENTS.md.

classDiagram
   App <|-- Console
   Console <|-- UmlDiagram
   Console <|-- NavbarComponent
   Console : - edges
   Console : - nodes
   Console : + handleCopy()
   Console : + createTable()
   Console : + onEventNodesChange()
   Console : + onEventEdgesChange()

   UmlDiagram : - gridTable
   UmlDiagram : + viewComment
   UmlDiagram : + objectComment
   UmlDiagram : + insertMode
   UmlDiagram : + findIndex()
   UmlDiagram : + addRow()
   UmlDiagram : + deleteRow()
   UmlDiagram : + handleNavigation()
   UmlDiagram : + handleObjectClick()

   NavbarComponent : - sideBarView
   NavbarComponent : + onEventExportJSON()
   NavbarComponent : + onEventImportJSON()
   NavbarComponent : + onEventCreateTable()
Loading

Console Design (Container Component)

View: The Console component is divided into two sections:

  1. NavbarComponent — Uses createTable and handleCopy to modify parent state
  2. React Flow Grid — Uses UmlDiagram as custom nodes:
const nodeTypes = { umlDiagram: UmlDiagram };

State: The node data structure:

{
  id: `node-${nodes.length + 1}`,
  type: "umlDiagram",
  position: { x: 10, y: 10 },
  data: {
    objectName: "Object Name",
    comment: "Object Description",
    color: getRandomColor(),
    gridTable: [
      {
        visibility: "+",
        signature: "",
        type: "",
        comment: "signature description",
      },
    ],
  },
}

This data is passed to UmlDiagram via the data prop and modified through:

  • addRow() / deleteRow() — Manage entity fields
  • handleObjectClick() — Select/focus entities
  • handleNavigation() — Keyboard navigation within the grid

Backend Architecture

Follows Clean Architecture principles (see AGENTS.md):

domain/ → use_cases/ → infrastructure/
  • domain/entities.py — Business entities and DAOs
  • use_cases/ — Business logic, DTOs, and ports
  • infrastructure/ — Adapters, routes, clients, and external contracts

Usage

Quick Start

  1. Launch the ORM builder:
dev ui path,to,devOS

  1. Design your entities:

    • Drag nodes onto the canvas
    • Define fields with types and relationships
    • Add constraints and validation rules

  2. Export specification:

Use the drawORM save/export action in the UI. It writes to specs/dao_spec.json.

  1. Generate code:
dev build project_name
  1. Implement use cases:

Write your business logic in use_cases/use_cases.py using the generated DTOs and DAOs.

  1. Run tests:
pytest tests/

Working with Ralph Locally

  1. Pull prompt and instruction updates:
dev-sync read_agents
dev-sync read_ralph
  1. Run your local Ralph workflow:
  • Execute ralph.sh with your preferred local runtime setup
  • Keep generated or updated instructions aligned with project conventions
  1. Push local prompt edits back to snippets:
dev-sync write_agents
dev-sync write_ralph

Managing Snippets

  1. List available snippets:
dev get snippets
  1. Pull snippet into project:
dev get snippet from python,sqlalchemy_adapter.py to path,to,local,sqlalchemy_adapter.py
  1. Update snippet from project:
dev set snippet from path,to,local,adapters.py to python,database-adapters,adapters.py
  1. Create custom snippet:
dev delete snippet python,database-adapters,adapters.py
  1. Use the local sync alias for prompts docs/scripts:
dev-sync read_agents
dev-sync write_agents

Configuration

Edit specs/project_config.json to customize:

{
  "home_root": {
    "vault_path": ["vault"],
    "snippets_repo": "https://github.com/your-org/devos-snippets"
  },
  "project_root": {
    "dao_output_config": [
      { "directory": ["src", "my_app", "domain", "dao.py"], "language": "python" }
    ],
    "dto_output_config": [
      { "directory": ["src", "my_app", "use_cases", "dto.py"], "language": "python" }
    ],
    "api_output_config": [
      {
        "directory": ["src", "my_app", "infrastructure", "routes.py"],
        "language": "python"
      }
    ],
    "test_api_output_config": [
      { "directory": ["tests", "test_routes.py"], "language": "python" }
    ],
    "test_services_output_directory": ["tests"],
    "contract_sync_output_config": [
      {
        "source_language": "python",
        "output_directory": ["src", "typescript_code", "schema"]
      },
      {
        "source_language": "typescript",
        "output_directory": ["src", "python_code", "schema"]
      }
    ]
  }
}

Any class inside files containing @contract is translated to the opposite language using the same filename stem. Example: types.ts -> types.py in the configured destination.

Why devOS?

The Problem

With LLMs, we can generate high-quality code faster than ever. But we still:

  • Write throwaway prototypes that never get refactored
  • Lack tests and documentation
  • Rebuild the same patterns across projects
  • Struggle to maintain consistency in large teams

The Solution

devOS bridges the gap between prototype and production:

  1. Visual design tools eliminate manual boilerplate
  2. JSON specifications ensure portability and type safety
  3. Ralph-first local workflows keep automation under your control
  4. Version-controlled snippets standardize patterns across projects
  5. LLM integration handles unsupported languages and edge cases

When to Use devOS

✅ Use devOS when:

  • Starting a new project that needs Clean Architecture
  • Refactoring a prototype into production code
  • Standardizing patterns across multiple projects
  • Working on proprietary code that can't use cloud AI services
  • You want generated tests, docs, and scaffolding automatically

❌ Don't use devOS when:

  • Building a quick throwaway script
  • Project structure is too unique for code generation
  • Team prefers full manual control over every file

Contributing

devOS is designed to be forked and customized. To contribute:

  1. Fork the repository
  2. Update snippets, templates, or generators
  3. Submit a PR with your improvements
  4. Or keep your fork private and sync upstream changes periodically

License

MIT License — See LICENSE for details.

Roadmap

  • Support for more programming languages (Go, Rust, Java)
  • GraphQL schema generation
  • Integration with more task management tools (Jira, Linear, etc.)
  • Real-time collaboration on drawORM canvas
  • Export to OpenAPI/Swagger specifications
  • Plugin system for custom code generators

Built with ❤️ by developers who are tired of rewriting the same code.

About

boiler plate code generator (DTO, DAO, CRUD Routes etc..) for clean architecture from JSON spec

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages