DryDrop

Composable fullstack project generator

DryDrop is a composable full-stack project generator written in Rust. Its goal is to let you assemble a clean, maintainable full-stack project skeleton by choosing building blocks (web frameworks, databases, auth, UI, etc.) like Lego pieces.

---

✨ Features (Planned)

• Modular Composition: Declare the modules your project needs; dependencies, conflicts, and file merging are handled automatically.
• Virtual File System (VFS): Build and merge file trees entirely in memory with support for diff/patch/merge operations.
• Template Rendering: Strong-typed templates powered by Askama for high-quality generated code.
• Plugin System: Inject custom logic at various stages of generation via hooks.
• Template Registry: Search, install, and update remote templates and modules.
• Multiple Interfaces: CLI, TUI, and Desktop app (planned).
• Safe File Operations: Read/write with automatic backups, suitable for updating existing projects.

---

🏗️ Architecture

DryDrop is organized as a Cargo workspace. Core logic lives under crates/, while user-facing applications are under apps/.

.
├── apps/
│   ├── cli/           # Command-line interface (drydrop)
│   ├── tui/           # Terminal UI (planned)
│   └── desktop/       # Desktop application (planned)
│
├── crates/
│   ├── drydrop-core/       # Core domain models
│   │   ├── project/        # Project / ProjectName
│   │   ├── module/         # Module / ModuleId / ModuleName
│   │   ├── dependency.rs   # Module dependency declarations (required / conflicts)
│   │   └── error.rs
│   │
│   ├── drydrop-vfs/        # Virtual File System
│   │   ├── path.rs         # VfsPath
│   │   ├── node.rs         # Node = File | Directory
│   │   ├── file/           # FileNode + FileContent
│   │   ├── directory/      # DirectoryNode
│   │   ├── tree.rs         # File tree structure
│   │   └── merge.rs        # Merge strategy for files from multiple modules
│   │
│   ├── drydrop-template/   # Template abstraction and loading
│   │   ├── template/mod.rs # Template trait
│   │   ├── loader.rs       # Template loader
│   │   ├── manifest.rs     # Template manifest
│   │   └── metadata.rs
│   │
│   ├── drydrop-generator/  # Generation pipeline
│   │   ├── planner.rs      # Plan file operations based on modules
│   │   ├── resolver.rs     # Resolve module dependency graph
│   │   ├── validator.rs    # Validation (conflicts, missing dependencies, etc.)
│   │   ├── pipeline.rs     # Execute the generation flow
│   │   └── generator.rs
│   │
│   ├── drydrop-render/     # Rendering engine
│   │   └── askama.rs       # Askama integration
│   │
│   ├── drydrop-diff/       # diff / patch / merge
│   │   └── ...             # Used for incremental updates on existing projects
│   │
│   ├── drydrop-fs/         # Safe filesystem operations
│   │   ├── reader.rs
│   │   ├── writer.rs
│   │   └── backup.rs       # Automatic backup before writes
│   │
│   ├── drydrop-plugin/     # Plugin system
│   │   ├── plugin.rs
│   │   ├── context.rs      # Plugin execution context
│   │   ├── hooks.rs        # Lifecycle hooks
│   │   └── exports.rs
│   │
│   └── drydrop-registry/   # Template / plugin registry
│       ├── registry.rs
│       ├── search.rs
│       ├── install.rs
│       └── update.rs
│
├── templates/              # Built-in templates (Askama)
│   └── askama/
│       ├── axum/
│       └── actix/
│
├── examples/               # Example projects
└── plugins/                # Plugin examples

Core Data Flow (Planned)

User selects modules
     │
     ▼
drydrop-core (Project + Modules + Dependencies)
     │
     ▼
drydrop-registry (Resolve remote modules/templates)
     │
     ▼
drydrop-generator
  ├─ resolver   → Build dependency graph
  ├─ planner    → Produce VFS operation plan
  ├─ validator  → Conflict / dependency checks
  └─ pipeline   → Execute
     │
     ▼
drydrop-vfs (Assemble final file tree in memory)
     │
     ▼
drydrop-render (Askama template rendering)
     │
     ▼
drydrop-fs (Write to disk with backup)
     │
     ▼
drydrop-plugin (post-generate hooks)

---

🚀 Quick Start

Requirements

• Rust (recommended to manage via mise)
• The project pins Rust 1.96.0 (see mise.toml)

# Install the Rust version specified by the project
mise install

Build

cargo build --workspace

Run the CLI

# Show help
cargo run -p cli -- --help

# Create a new project (currently a placeholder)
cargo run -p cli -- new my-app

---

🛠️ Development Guide

Common Commands

# Check compilation (recommended during development)
cargo check --workspace

# Run tests
cargo test --workspace

# Build release
cargo build --release --workspace

# Build only the CLI
cargo build -p cli

Adding a New Module Type

1. Extend Module / ModuleId definitions in drydrop-core.
2. Add discovery and installation support in drydrop-registry.
3. Add corresponding Askama templates under templates/.
4. Handle module-specific logic (route registration, DI, etc.) in drydrop-generator's resolver/planner.
5. Implement hooks in drydrop-plugin if custom behavior is needed.

Template Development

Templates currently live in templates/askama/<framework>/.

• Files with the .askama suffix are processed by Askama.
• Keep the template structure close to the final generated project to ease maintenance.

VFS and File Merging

drydrop-vfs is a core abstraction. Files generated by multiple modules are merged using strategies defined in merge.rs.

Common merge strategies (to be implemented):

• Direct overwrite (new files)
• Append content (routes, dependencies, etc.)
• Smart merge (using diff/patch)

Error Handling

Currently uses drydrop-core::error::Result (a type alias over std::result::Result).

Future work may migrate to snafu for richer error context (already declared in the workspace).

Plugin Hook Points (Planned)

Hook Stage	Description
pre_resolve	Before dependency resolution
post_resolve	After dependency resolution
pre_generate	Before file generation
post_generate	After file generation (VFS ready)
pre_write	Before writing to disk
post_write	After writing to disk

---

📊 Current Status

Component	Status	Notes
CLI (drydrop new)	Skeleton	Command parsing done; real logic is stub
drydrop-core	Model defined	Project / Module / Dependency etc.
drydrop-vfs	Model defined	Basic node and path structures
drydrop-template	Interface	Template trait + module layout
drydrop-generator	Module layout	pipeline/resolver/etc. modules created
Other crates	Placeholder	Most implementations are empty
Templates	Directories	Files are empty; real templates pending

Total code: ~200 lines of effective Rust (as of the initial commit).

This is a very early-stage project and is intended as a foundation for long-term evolution.

---

🗺️ Suggested Development Roadmap

1. MVP Generation Flow

   • Make drydrop new <name> --template axum produce a runnable project
   • Complete Askama rendering + VFS write path

2. Module System

   • Define built-in modules (web, db, auth, ...)
   • Implement dependency resolution + conflict detection

3. VFS Merge Strategies

   • File-level and content-level merging
   • Support drydrop add <module> on existing projects

4. Plugin System

   • Define Hook traits
   • Implement a simple example plugin

5. Registry

   • Local template index
   • Later: remote repository support

6. TUI / Desktop

   • Interactive module selection UI

---

📁 Directory Responsibilities (Quick Reference)

Path	Responsibility
apps/cli	CLI entry point + subcommand implementations
crates/drydrop-core	Domain models (prefer immutable data)
crates/drydrop-vfs	In-memory file tree + merge logic
crates/drydrop-generator	Generation orchestration (most complex core)
crates/drydrop-template	Template abstraction and loading
crates/drydrop-render	Concrete renderer (Askama)
crates/drydrop-registry	Distribution of templates/modules/plugins
crates/drydrop-plugin	Extension points and lifecycle hooks
crates/drydrop-fs	Disk I/O + backup
crates/drydrop-diff	Diff & patch (for incremental updates)
templates/	Built-in template sources

---

🤝 Contributing

Contributions of any kind are welcome! At this stage, the most valuable contributions include:

• Implementing core logic in any crate
• Writing the first working Askama template
• Designing and implementing the module dependency resolver
• Adding tests and documentation

Before submitting a PR, please ensure:

cargo check --workspace
cargo test --workspace
cargo clippy --workspace -- -D warnings

---

📄 License

MIT © 2026 NotNOne

---

🔗 Related Resources

• Askama — Type-safe template engine
• Clap — Command line argument parsing
• Snafu — Error handling

---

Note: This project is in an early design and scaffolding phase. The README will be updated continuously as implementation progresses. Before developing, it's recommended to first explore the module layout and public APIs of the relevant crates.

---

Chinese Documentation: See Docs/README_zh_CN.md