Developer Overview

Welcome to the Portosaur Developer Guide. This section is intended for developers and power users who want to extend the project.

Monorepo Architecture

Portosaur is structured as a monorepo. This ensures a clear separation between the CLI, the core logic, and the user-facing themes.

Package Layout

NOTE

Some of the packages are independent/standalone packages that can be used with any projects

Package	Purpose	Key Responsibilities
@Portosaur/cli	Orchestrator	Command registration (init, dev, build), Docusaurus shimming, and CLI entry point.
@Portosaur/core	Translation layer	YAML configuration parsing, recursive variable resolution, and system utility suite.
@Portosaur/theme	Visual Core	React components, plugins, CSS styles, and default static assets.
@Portosaur/wizard	Prompt Library	Standalone prompt library with built-in history replaying and back-navigation.
@Portosaur/logger	Logging Library	Standalone Logger library, brings Docusaurus style logging with extra functionalities.

Core Logic Flow

1. Initialization: The init command uses @Portosaur/wizard to gather user intent, then leverages @Portosaur/core utilities to mirror templates and generate a config.yml.
2. Development/Build: When Portosaur dev or Portosaur build is executed, the CLI generates a temp Docusaurus config shim that dynamically imports the config builder from @Portosaur/core, which resolves assets pointing to @Portosaur/theme.
3. Variable Resolution: The configuration builder in core performs a recursive pass over the YAML data, resolving {​{...}​} tags from system variables, environment variables, and user-defined custom keys.