Architecture

This document outlines the architecture for the Jasonelle cross-platform web wrapper generator framework.

Architecture Overview

The system is designed around a cascading asset injection strategy, a modular CLI approach, and a strictly separated directory structure.

  1. Cascading Configuration & Assets: lib/common/ is the base layer. Platform directories (lib/xcode/, lib/android/) override or extend it — same path, platform wins.

  2. Native File Overrides: Placing a file in lib/<platform>/sources/ automatically replaces the corresponding file from sources/<platform>/ during the build.

  3. Store Metadata: config/store.jsonc and .env manage store metadata and secrets. task jsonc merges them per platform into build/xcode and build/android.

  4. TypeScript Bundling: the bundler tool merges TypeScript files from lib/common and lib/<platform> into a single webview.js. Common scripts are copied first, platform scripts overlay on top.

  5. Unified Build Pipeline: the gen tool (run via the Taskfile gen task) orchestrates the Go tools icon, jsonc, bundler, plugins, core, link and appconf to assemble both build/xcode and build/android from the same lib/ and sources/ inputs.

Build Pipeline

The build pipeline turns the user workspace (lib/) and the stock templates (sources/) into two runnable native projects under build/. The gen tool (task gen, or tools/gen/dist/gen-<os>-<arch>) runs the steps in order for both platforms:

Step Tool Writes to Responsibility

1

icon

lib/<platform>/assets/

Generates the Android and Xcode app icons from lib/common/assets/icon/1024x1024.png.

2

jsonc

build/<platform>/config/

Merges the cascading config.jsonc and store.jsonc files (lib/common merged with the platform overrides).

3

bundler

build/<platform>/scripts/

Bundles the TypeScript scripts (lib/common/scripts + lib/<platform>/scripts) into a single webview.js via the vendored esbuild.

4

plugins

build/<platform>/sources/

Copies the plugins declared in the merged per-platform configs so only configured plugins reach the project.

5

core

build/<platform>/sources/

Assembles the app source tree (sources/<platform> + lib/<platform>/sources overrides), preserving files the previous steps generated.

6

link

build/<platform>/sources/

Links the plugin projects into the Xcode workspace, the Android Gradle files and the Application project, and copies the built config.jsonc and webview.js into the assembled app.

7

appconf

build/<platform>/sources/

Rewrites PRODUCT_BUNDLE_IDENTIFIER / applicationId from the app_id in the merged configs, and sets the app name and the version / build number from app_name and app_version.

After the last step each build/<platform>/ directory contains a complete, configured native project ready to open and build.

C4 Architecture Diagram

The diagram below shows the current architecture. The gen tool runs the icon, jsonc, bundler, plugins, core, link and appconf Go tools in order for both platforms, reading from lib/ and sources/ and writing to build/.

c4_architecture

Architecture Flow Diagram

The diagram below shows the data flow through the build pipeline.

architecture_flow

Directory Structure

  • .gitignore: Excludes .env and build/.

  • sources/: Base project templates.

    • sources/xcode/: Xcode project template (Swift, storyboards, workspace).

    • sources/android/: Android Studio project template (Kotlin, Compose, Gradle).

  • lib/: User workspace for configurations and overrides.

    • lib/common/:

      • .env: Secret keys for tools and stores.

      • config/config.jsonc: Foundational configuration.

      • config/store.jsonc: Shared app store metadata.

      • config/bundler.json: TypeScript config for esbuild.

      • assets/icon/1024x1024.png: Base icon for store listings.

      • resources/: Raw files copied to the app bundle.

      • scripts/main.ts: Base TypeScript entry point for the webview.

    • lib/android/:

      • config/config.jsonc: Android configuration overrides.

      • config/store.jsonc: Play Store specific overrides.

      • scripts/main.ts: Android TypeScript overrides.

      • sources/: Native file replacements (e.g., custom MainActivity.kt).

      • assets/: Play Store specific assets.

      • resources/: Raw files copied to the Android app bundle.

    • lib/xcode/:

      • config/config.jsonc: Xcode configuration overrides.

      • config/store.jsonc: App Store specific overrides.

      • scripts/main.ts: Xcode TypeScript overrides.

      • sources/: Native file replacements (e.g., custom ContentView.swift).

      • assets/: App Store specific assets.

      • resources/: Raw files copied to the Xcode app bundle.

  • tools/: CLI tools and vendored binaries.

    • tools/gen/: Runs the full build pipeline (icon, jsonc, bundler, plugins, core, link, appconf) as the Taskfile would (Go).

    • tools/icon/: Generates per-platform app icons from a 1024x1024 PNG (Go).

    • tools/jsonc/: Merges cascading JSONC config files (Go).

    • tools/bundler/: Bundles TypeScript into webview.js via esbuild (Go).

    • tools/plugins/: Copies the configured plugins into the build sources (Go).

    • tools/core/: Assembles the app source tree, overlaying overrides (Go).

    • tools/link/: Links plugins into the native projects and copies app artifacts (Go).

    • tools/appconf/: Sets the app identifiers, name and version / build number from the merged configs (Go).

    • tools/vendor/esbuild/: Vendored esbuild binary for TypeScript bundling.

  • build/: Generated output (git-ignored).

    • build/xcode/: Assembled Xcode project.

      • config/: Merged config.jsonc and store.jsonc.

      • scripts/: Bundled webview.js.

      • sources/: Assembled Xcode source tree with linked plugins and app artifacts.

    • build/android/: Assembled Android Studio project.

      • config/: Merged config.jsonc and store.jsonc.

      • scripts/: Bundled webview.js.

      • sources/: Assembled Android source tree with linked plugins and app artifacts.