Skip to main content

APIS Core

APIS is the orchestration layer that turns project relationships into executable automation.

At the core level, APIS is responsible for loading project context, resolving modules, building a dependency graph, and deciding what should happen next in a repository-aware workflow.

What the core does​

The current codebase already shows the main APIS runtime responsibilities:

  • load APIS configuration from a project directory such as .apis
  • load APIS-related environment variables from the system and from an .env file
  • connect to the current Git repository and GitLab when credentials are available
  • detect versions and branch flags
  • load built-in and project-specific modules
  • resolve jobs and items into a flow graph
  • generate execution plans for local runs or CI/CD pipelines

In other words, the core is the part that understands the project as a system, not just as a folder of scripts.

Entry points​

The apis command-line interface is the main entry point.

The current CLI supports options for:

  • log level
  • environment file location
  • branch override
  • configuration directory
  • push-enabled mode for external changes

It also exposes actions such as:

  • printing the APIS version
  • listing loaded modules
  • checking a version tag
  • incrementing version data
  • generating a plan

If no direct action is requested, APIS currently falls back to its terminal UI.

Project context​

APIS builds its runtime state from three sources:

  1. the current repository
  2. APIS environment variables
  3. the APIS configuration directory

This makes it possible to run the same project logic:

  • locally on a developer machine
  • inside CI/CD
  • inside workflow automation such as Git-based pipelines

That shared context is what allows APIS to keep dependent repositories aligned without rewriting automation logic for every environment.

Git and version awareness​

The core already includes Git-aware behavior through ApisGit.

When repository access and authentication are available, APIS can:

  • inspect the current remote
  • detect the current repository and branch
  • inspect tags
  • map the current commit
  • push or rewrite tags when push mode is enabled

Version handling is also built into the core runtime.

APIS loads version information from:

  • Git tags
  • environment variables such as APIS_DATA_VERSION
  • branch naming rules

The branch model already supports flags such as:

  • main
  • beta
  • alpha
  • dev

It also parses branch metadata like marks and major locks from the branch name. That gives APIS a structured way to align automation behavior with release lanes.

Module loading​

The core does not hardcode project behavior directly.

Instead, it loads:

  • built-in modules that ship with APIS
  • project modules from the configured modules directory

After loading, APIS resolves those modules into:

  • artifact nodes
  • job nodes
  • input and output relationships

That resolution step is what makes flow generation possible.

Flow generation​

Once modules are loaded, APIS converts them into a dependency graph made of jobs and items.

This graph is used to determine:

  • which artifacts exist in the project
  • which jobs provide them
  • which jobs consume them
  • what order of execution is valid

The current codebase already includes flow graph generation, graph serialization, and Mermaid or HTML-oriented visualization output.

This is the technical foundation behind the larger APIS idea: when one repository changes, downstream project data should be updated through a known dependency path rather than through manual communication.

Environments and execution​

The core also defines interfaces for environments and executors.

That separation matters because APIS needs to answer two different questions:

  • what is available in the current project environment
  • how should the work actually be executed

Keeping these concerns separate allows APIS to remain modular even when projects differ in infrastructure or runtime strategy.

Current maturity​

The repository already contains a meaningful core architecture:

  • CLI entry point
  • module system
  • Git integration
  • version logic
  • flow model
  • trigger foundations
  • terminal UI components

Some user-facing methods are still placeholders, but the structural backbone is already visible and strong enough to describe APIS as a real orchestration framework rather than a concept only.