1. Core Web App Functionality (Runtime)

The primary function of repo.md is to take a public GitHub repository URL and generate a single Markdown document representing its structure and content. This process is handled by Go WASM (WebAssembly) which executes directly in the browser when a user interacts with the application.

1. User Input: A user enters a GitHub repository URL into the input field on the repo.md homepage (capacitor/src/index.html).
2. WASM Initialization: Upon page load, a Web Worker loads and initializes the Go WASM module (main.wasm):
   • The worker first loads wasm_exec.js (provided by Go) to set up the WASM environment.
   • Then it instantiates the compiled WASM module (main.wasm) which contains the Go code.
   • The Go runtime starts in the worker thread, running independently from the main browser thread.
3. GitHub API Processing (wasm/main.go):
   • When the user submits a GitHub URL, the frontend JavaScript sends this to the WASM module via the worker.
   • The Go code in the worker makes direct HTTP requests to the GitHub API to retrieve repository information.
   • It fetches the repository structure and file contents using GitHub's REST API endpoints.
   • All processing happens directly in the browser - no server-side processing is needed.
4. Markdown Generation (wasm/main.go):
   • The Go code parses the GitHub API responses and organizes the repository structure.
   • It processes each file, checking content type and determining if it's binary or text.
   • For each text file, the content is retrieved and embedded in Markdown code blocks.
   • The process creates a single, comprehensive Markdown document that represents the entire repository.
   • File size limits and binary detection are implemented to prevent memory issues.
5. Response: The WASM module sends the generated Markdown back to the main thread via a callback function.
6. Display: The frontend JavaScript populates a <pre><code> block with the received Markdown and enables the "Copy to Clipboard" and "Download .md" buttons.
7. Client-side Execution: Since all processing happens in the browser via WASM, there's no need for server cleanup or temporary directories.

The following diagram shows the runtime process of how a GitHub repository URL is processed by the deployed repo.md web app to generate Markdown content:

2. Web App GitOps Deployment to Fly.io

The repo.md web application's deployment to Fly.io is managed via a GitOps workflow. Changes pushed to the main branch automatically trigger a new build and deployment.

1. Git Push: A developer pushes code changes (e.g., to Go code in wasm/main.go, or frontend files in capacitor/src/) to the main branch of the repo.md GitHub repository.
2. GitHub Actions Trigger: This push automatically triggers the .github/workflows/fly-deploy.yml workflow.
3. Workflow Execution:
   • The repository code is checked out on an ubuntu-latest runner.
   • The Fly.io CLI (flyctl) is set up.
   • flyctl deploy --remote-only is executed. This command tells Fly.io to:
     • Pull the latest code from the main branch.
     • Build a new Docker image using the Dockerfile in the repository root. The Dockerfile defines a multi-stage build process that:
     • Compiles the Go WASM module from wasm/main.go using the Go compiler
     • Builds and serves static frontend assets along with the compiled WASM file
     • Deploy this new image to the Fly.io infrastructure as defined in fly.toml.
4. Live Application: Once Fly.io successfully builds and deploys the new version, it becomes the live application accessible at repo-md.com.

This GitOps deployment pipeline is visualized below:

3. iOS App GitOps Build & Deployment

The repo.md iOS application, a Capacitor-wrapped version of the web app, also follows a GitOps approach for builds and deployments to TestFlight, leveraging GitHub Actions and Fastlane.

3.1. Prerequisite: iOS Code Signing (ios-match-init.yml)

Code signing is a critical part of iOS development. Fastlane Match is used to manage certificates and provisioning profiles, storing them securely in a separate private Git repository (bobbyhiddn/fastlane). This setup is an example of "Infrastructure as Code."

1. Manual Initialization: The .github/workflows/ios-match-init.yml workflow is run manually when new certificates are needed (e.g., initial setup, yearly renewal).
2. Certificate Generation: This workflow securely generates and stores the necessary signing identities and provisioning profiles in the dedicated Match Git repository.

3.2. Automated iOS Deployment to TestFlight (ios.yml)

Changes to the web application's codebase or manual triggers can initiate an automated build and deployment of the iOS app to TestFlight.

1. Git Push / Manual Trigger:
   • A push to the main branch (if relevant web app files like .html, .js, .css, or .go for potential WASM changes are modified) triggers the .github/workflows/ios.yml workflow.
   • Alternatively, the workflow can be dispatched manually with versioning options.
2. GitHub Actions Workflow Execution (ios.yml):
   • The workflow first checks if a build is necessary and if the Match repository is set up.
   • Web Asset Build: The latest web application code from the main branch is built (e.g., using Vite via npm run build).
   • Capacitor Sync: npx cap sync ios integrates these fresh web assets into the native iOS project structure.
   • Fastlane Execution: The closed_beta lane in capacitor/ios/App/fastlane/Fastfile is executed. Fastlane handles:
     • Fetching code signing assets from the Match Git repository.
     • Incrementing app version and build numbers.
     • Building the native iOS application (.ipa file).
     • Uploading the .ipa to App Store Connect for TestFlight distribution.
3. TestFlight Release: Once App Store Connect processes the build, it becomes available to testers via TestFlight.

This automated iOS build and deployment pipeline is shown below: