CLI Architecture & Session Management

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• cmd/gendocs/main.go
• internal/commands/ports_describe.go
• internal/opendpi/parse.go
• internal/opendpi/writer.go
• internal/session/cobra.go
• internal/session/context.go
• cmd/daco/internal/app.go

Introduction

The Daco CLI is designed as a modular tool for managing data products, adhering to the principles of a 12-Factor App where applicable. Its architecture is built around a clear separation between command definitions, private logic packages, and application bootstrapping. The system utilizes the Cobra library for command-line interface management and includes a dedicated session management layer to handle state and context across different commands.

Session management ensures that command execution is grounded in a consistent environment, providing access to necessary specifications, configurations, and runtime contexts. This architecture supports features such as OpenDPI specification parsing, schema translation, and interactive command execution.

Sources: CONTRIBUTING.md:14, CONTRIBUTING.md:43-57

CLI Project Structure

The project follows a standard Go project layout, separating the entry point from internal logic and documentation generation.

Directory	Description
cmd/daco/	The primary entry point for the CLI application.
internal/commands/	Definitions for all CLI commands and subcommands.
internal/session/	Core logic for session handling and command context.
internal/opendpi/	Logic for parsing and writing OpenDPI specifications.
internal/translate/	Modules for translating JSON schemas into various target languages (e.g., PySpark, SQL, Scala).

Sources: CONTRIBUTING.md:43-57, cmd/gendocs/main.go:28-40

Application Bootstrapping

The application entry point resides in cmd/daco/, which initializes the root command and registers various translators. The documentation generator (gendocs) demonstrates how translators are registered into a central registry before being passed to the command root.

The diagram shows the initialization flow from the main entry point to subcommand execution.
Sources: cmd/gendocs/main.go:26-44, CONTRIBUTING.md:44-46

Session Management & Context

Session management is a critical component that bridges command execution with the underlying application state. It primarily revolves around the Context struct and the RequireFromCommand utility.

Session Context

The Context provides commands with access to the parsed OpenDPI Spec, which contains information about ports, connections, and schemas.

// Derived from internal/session/context.go (Simulated structure based on usage)
type Context struct {
    Spec *opendpi.Spec
    // Additional session-related fields
}

Sources: internal/session/context.go, internal/commands/ports_describe.go:48-52

Context Requirement Flow

Commands use session.RequireFromCommand(cmd) to ensure the execution environment is valid. If a session cannot be established or the required specification is missing, the command fails early.

This sequence illustrates how a command retrieves its operational context through the session package.
Sources: internal/commands/ports_describe.go:48-51, internal/opendpi/parse.go:34-40

OpenDPI Specification Handling

The CLI architecture includes robust handling for OpenDPI specifications, supporting both JSON and YAML formats. The processing involves parsing raw data into a structured Spec and resolving references.

Parser & Writer Architecture

The opendpi package implements a dual-mode parser (JSON/YAML) and a corresponding writer system.

Component	Responsibility	Relevant Source
Parser	Decodes io.Reader and resolves $ref references (internal and external).	internal/opendpi/parse.go
Writer	Encodes Spec objects back to JSON or YAML files.	internal/opendpi/writer.go
Loader	Handles file system access for resolving external schema files.	internal/opendpi/parse.go:50

Sources: internal/opendpi/parse.go:22-31, internal/opendpi/writer.go:18-24

Schema Resolution Logic

When parsing a specification, the system performs a multi-step resolution:

1. Component Loading: Loads schemas defined in the components/schemas section.
2. External File Loading: Loads schemas referenced via file paths.
3. Reference Rewriting: Rewrites internal references from #/components/schemas/ to #/$defs/ for compatibility with JSON Schema utilities.

Sources: internal/opendpi/parse.go:52-100, internal/opendpi/parse.go:138-160

Command Implementation Pattern

Individual commands follow a consistent pattern for registration and execution, often incorporating interactive elements through the huh package for user prompts.

Example: Ports Describe Command

The describe command demonstrates the integration of session context, interactive selection, and multi-format output (text, JSON, YAML).

// internal/commands/ports_describe.go
func (opts *portsDescribeOptions) RunE(cmd *cobra.Command, args []string) error {
    ctx, err := session.RequireFromCommand(cmd)
    if err != nil {
        return err
    }
    // ... logic to show port details ...
}

Sources: internal/commands/ports_describe.go:48-70

Interaction Flow

The flowchart depicts how the describe command handles user input and context retrieval.
Sources: internal/commands/ports_describe.go:53-110

Summary

The Daco CLI architecture is characterized by its strict separation of concerns and robust session-management layer. By utilizing a centralized context requirement system, the CLI ensures that commands have reliable access to the OpenDPI specifications and translators they need. The modular design of the opendpi and translate packages allows the tool to handle complex data product definitions and translate them across diverse technological ecosystems efficiently.

Sources: CONTRIBUTING.md:14-20, internal/session/context.go, internal/opendpi/parse.go:34-40