Directory Structure (Blueprint)

The Dracory Blueprint is the recommended starter layout for new Dracory apps. It provides clear separation of concerns and follows Go standard project layout patterns.

Root

Top-level folders in the Blueprint repository:

• .github/ – CI workflows, e.g., workflows/tests.yml.
• .vscode/ – Editor settings and launch configs.
• cmd/ – CLI apps (e.g., server, deploy, envenc, ai-browser, loadtest).
• internal/ – Application code (app boot, controllers, stores, etc.).
• pkg/ – Reusable packages exported for import by other projects.
• Project files: go.mod, Dockerfile, taskfile.yml, etc.

cmd

Command-line applications:

• cmd/server/ – Main application entry point. Split into main.go, background.go, background_processes.go, and cli_mode.go for clean separation of server lifecycle, background workers, and CLI mode.
• cmd/ai-browser/ – Sandboxed, auto-authenticated instance of the app for AI/browser UI testing (disposable SQLite DB, external APIs disabled).
• cmd/deploy/ – Deployment utility.
• cmd/envenc/ – Environment encryption utility.
• cmd/loadtest/ – Load testing utility.

Internal

Key internal packages (Blueprint):

• internal/app/ – App bootstrap, lifecycle, stores wiring (datastores.go), database connection (database_open.go), and migrations.
• internal/cache/ – Cache interfaces and implementations.
• internal/cli/ – CLI entry points and flags; cli.go bundles commands.
• internal/cmds/ – CLI command implementations dispatched via github.com/dracory/base/cli.
• internal/cmsblocks/ – CMS block type components (e.g., blogpost).
• internal/config/ – Configuration system with Blueprint-style environment loading. Contains constants.go (env keys), config_interfaces.go (interfaces), config_implementation.go (implementation), section-specific loaders (app_config.go, auth_config.go, database_config.go, email_config.go, etc.), store_builders.go (store factory functions), and version.go.
• internal/controllers/ – Admin/Auth/User/Website controllers and their routes. Admin screens are provided by the external github.com/dracory/blogadmin, shopadmin, logadmin, fileadmin, and useradmin modules, wired in via internal/controllers/admin/adapters/ (admin layout, LLM factory, customer resolver).
• internal/emails/ – Email templates and sending logic.
• internal/ext/ – External integrations.
• internal/helpers/ – Small shared helpers (flash messages, payment codes, user-role checks via UserHasActiveRole). Session helpers live in github.com/dracory/base/session.
• internal/layouts/ – Application layout wrappers built on github.com/dracory/base/layouts option types.
• internal/links/ – Centralized route constants.
• internal/middlewares/ – HTTP middlewares.
• internal/models/ – Shared model definitions.
• internal/resources/ – Static resource handling (embedded assets).
• internal/routes/ – Router setup using github.com/dracory/rtr.
• internal/rules/ – Business rule definitions (e.g., rules/auth).
• internal/schedules/ – Scheduled job configuration.
• internal/tasks/ – Background task definitions, each in its own subdirectory. Includes internal/tasks/constants/ for compile-time safe task alias constants.
• internal/testutils/ – Test fixtures (seed_user.go, seed_session.go, login_as.go, etc.) and Setup() with automatic store migrations via migrations.MigrateAll. Generic test assertions come from github.com/dracory/test and github.com/dracory/base/testutils.
• internal/widgets/ – UI widget components.

pkg

Reusable packages included with the Blueprint:

• pkg/testimonials/ – Testimonial types and list handling.

Admin functionality is NOT under pkg/ – it lives in the standalone modules github.com/dracory/blogadmin, github.com/dracory/shopadmin, github.com/dracory/logadmin, github.com/dracory/fileadmin, and github.com/dracory/useradmin, integrated via internal/controllers/admin/adapters/.

Note: Other repos (like this website) may contain additional pkg/* modules (e.g., pkg/gos/, pkg/oop/, pkg/rag/, pkg/webtheme/). The Blueprint focuses on essentials.

Configuration

Configuration is env-driven and loaded from .env via internal/config. The entry point is config.NewFromEnv() which reads environment variables, hydrates encrypted values, validates required keys, and returns a config.ConfigInterface. Env keys are defined in internal/config/constants.go.

Assets & Templates

The Blueprint itself does not ship with public/ or views/ by default. Applications created from the Blueprint typically add these as needed.