Doh Project Structure

This document outlines the standard directory structure and key files you'll find in a Doh project, typically created using the doh init project (or doh init doh) command.

Overview

A standard Doh project provides a basic setup designed for modularity and robust configuration. Here's a look at the common top-level items:

/
├── .doh/              # Internal Doh files (cache, manifests - generally leave alone)
├── .vscode/           # VS Code specific settings (e.g., launch configurations)
│   └── launch.json
├── dbs/               # Default git-ignored and express-ignored folder for SQLite files
├── doh_js/            # Core Doh runtime files provided by the framework
│   └── manifests/     # Generated manifests for packages, patterns, etc.
├── doh_libs/          # Doh Package wappers for external libraries
├── doh_modules/       # DeployDoh.com official modules
├── modules/           # Standard location for your application's code (Custom Doh Packages/Modules)
├── secrets/           # Git-managed, Express-ignored directory for generic secrets
├── .gitignore         # Standard Git ignore file pre-configured for Doh
├── boot.pod.yaml      # Base configuration settings loaded first (part of repo)
├── doh.js             # Main project entry point script
├── package.json       # Node.js package definition and dependencies
└── pod.yaml           # Primary project instance configuration (local, not in repo by default)

Key Files and Directories

• doh.js:

  • The main entry point for your Doh application when run from Node.js or Bun.
  • It dynamically imports the correct Doh core entry point (./doh_js/index.js for server-side, ./doh_js/deploy.js for browser builds, although browser builds usually start from an HTML file). In this way, Doh has many entry points, but all of them funnel through ./doh_js/deploy.js as it is considered the true Doh Core, containing a large majority of the base Doh features.

• package.json:

  • Standard Node.js manifest file.
  • Doh ensures type: "module" is set for ES Module compatibility.
  • Managed by Auto-packager using a cache that tracks updates and enforces deps across installs with automatic packager install commands

• boot.pod.yaml:

  • A base configuration file that is loaded before pod.yaml.
  • Intended for settings required early in the boot process or shared across all instances.
  • Unlike pod.yaml, this file is not typically in .gitignore, allowing base configurations to be version-controlled.

• pod.yaml:

  • The primary configuration file for your specific project instance. This is where you define environment-specific settings, configure modules (host_load), set up webservers, manage database connections, and define inheritance from other Pod files.
  • Crucially, this file is typically included in .gitignore by default, as it often contains instance-specific settings or secrets.

• /modules/:

  • The recommended directory for organizing your application's functionality.
  • You'll create subdirectories here representing your Doh Packages or Modules. This promotes code reuse and separation of concerns. See Packages and Modules.

• /doh_js/:

  • Contains the core runtime files provided by the Doh framework itself. You generally shouldn't modify files within this directory directly. Updates are handled through the Doh CLI.
  • /doh_js/manifests/: Contains JSON files generated by Doh's internal systems (like the Auto-Packager or Pattern Engine) that describe the structure and components of your project (e.g., package_manifest.json, patterns_manifest.json). These are usually managed automatically. These are intended to be public, used by all environments to interact with your project.

• /.doh/:

  • Holds internal files used by Doh, such as private compiled manifests, cache files, backup directories (codex/, shrines/), and update/upgrade/install artifacts.
  • This directory is typically added to .gitignore. You generally don't need to interact with its contents directly, although CLI commands exist for cache clearing or backup management.

• .gitignore:

  • A standard .gitignore file pre-populated with common patterns to ignore files and directories specific to Node.js, Doh, and general development (e.g., node_modules/, .doh/, dist/, pod.yaml).

• /.vscode/launch.json:

  • If using Visual Studio Code or Cursor, this file provides pre-configured launch profiles for debugging your Doh application using the built-in debugger, supporting both the standard doh run flow and specific tasks like doh export.

Variations

• doh init webserver: This command initializes a similar structure but typically pre-configures pod.yaml with settings for the Express webserver module and creates a simple html and css page that can be hot edited in the base project root.
• Modules/Packages: As you add your own code in the /modules/ directory using Doh.Package() or Doh.Module(), the Auto-Packager will analyze these and update manifests within /doh_js/manifests/ and potentially /.doh/.