Stratum Build System

Stratum is a high-performance, layered build and synchronization tool designed for complex Java, Scala (Play Framework), and TypeScript projects. It allows teams to maintain a "Base Layer" (L1) of code while seamlessly overriding or extending functionality in higher layers without manual copy-pasting.

📂 Supported File Extensions for Compilation

• .java – Java source files.
• .conf – HOCON configuration files (e.g., application.conf).
• .scala.html – Play Framework Twirl templates.
• .ts – TypeScript source files.
• .js – JavaScript files.
• .json – Manifests and config files only for package.json.
• .scss – Style sheet assets.

🛠 Core Commands

| Command | Description | |:------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------| | stratum update | Clones/fetches remote repositories defined in dependencies.json and synchronizes L1 files into your local project based on updateDefinition.json. | | stratum compile | Scans your root directory, merges layered files (like package_*.json), and generates the "Shadow" environment in the shadowRoot. | | stratum clean | Removes generated shadow files and temporary update directories to ensure a fresh state. | | stratum watch | Watches all project files for changes or additions and automatically compiles them. |

⚙️ Configuration Files

1. dependencies.json

{
  "dependencies": [
    {
      "name": "core-l1",
      "type": "layer",
      "repository": "[email protected]:gecko/core-l1.git",
      "ref": "master",
      "targetPath": "app/com/gecko/web"
    },
    {
      "name": "auth-lib-l1",
      "type": "layer",
      "repository": "[email protected]:gecko/auth-lib.git",
      "ref": "v1.0.0",
      "targetPath": "app/com/gecko/lib/auth-lib"
    },
    {
      "name": "auth-lib-2",
      "type": "sub-project",
      "isLayered": true,
      "repository": "[email protected]:gecko/auth-lib-v2.git",
      "ref": "commit:ab20xc",
      "targetPath": "app/com/gecko/lib/auth-lib"
    }
  ]
}

This file acts as the project's manifest for external code. It tells the Updater where to find the source code for your layers and libraries.

• type: Defines if its a sub-project or a layer, use sub-project for the highest layer of the library as shown with auth-lib
• repository: The SSH Git URL.
• ref: Supports branches (master), tags (v1.0.0), or specific hashes (commit:ab20xc).
• targetPath: Crucial for isolation. This is where the files from that repository will be "shifted" to within your project. Note: The target path has to be the same as the repos folder structure and also needs to match the root path defined in the stratum.config.json

2. stratum.config.json

{
  "root": "app/com/gecko",
  "shadowRoot": "app/shadow",
  "mainProjectRoot": "app/com/gecko/web"
}

Defines the workspace boundaries for the Compiler and Shadow Generator.

• root: The entry point. Stratum recursively searches from here for all .java, .scala.html, .ts, .js and .scss files.
• shadowRoot: The "output" directory. Stratum creates a flat, compiled version of your layered project here, which the actual Java/Scala compiler then executes.
• mainProjectRoot: Specifies where the primary application logic begins, helping the compiler distinguish between library code and app code.

3. updateDefinition.json

{
  "overwrite": [
    "app/**/TemplateHelper.scala",
    "app/**/*L1.java",
    "app/**/*L1.ts",
    "app/**/*_l1.scala.html",
    "app/**/*_l1.scss",
    "app/**/*_l1.js",
    "**/*_l1.json",
    "conf/**/*_l1.conf",
    "conf/**/*l1.routes",
  ],
  "add": [
    "**/*_l1.sbt",
    "conf/logback*.xml",
  ],
  "merge": []
}

Located within the source repository, this file acts as a filter. It defines exactly which files are "allowed" to be pushed into your project during an update.

• overwrite: Patterns for files that should be updated if changed (e.g., app/**/*L1.java).
• merge: File where Stratum should attempt to merge remote changes with your local customizations using diff-match-patch.
• add: New files that should be introduced only if they don't already exist locally.

🔄 The Update Workflow

When you run stratum update, the following happens:

1. Shallow Checkout: Stratum performs a git clone --depth 1 for each dependency to save time and bandwidth.
2. Pattern Matching: It reads the updateDefinition.json from the temp folder.
3. Path Shifting: Files are moved from the temp folder to your targetPath.
   • Example: A remote file app/HelperL1.ts with target app/com/gecko/lib becomes [YourProject]/app/com/gecko/lib/app/HelperL1.ts.
4. Change Detection: Files are only written to disk if the content has actually changed, preserving file system timestamps and IDE performance.

🛡 Layering Convention

To get the most out of Stratum, follow the suffix convention:

• Increase the layer number by 1 as you go up
• Use FileNameL1 for .java and .ts files
• Use FileName_l1 for .scala.html, .scss, .conf, .json, .sbt and .js
• Use FileNamel1.routes for routes files and place them under conf/layeredRoutes they get compiled to one routes file under conf