Rendering & Publishing Architecture

​

V2 architecture

​

Ownership and stored artifacts

username/username
├── default branch (discovered from repository metadata)
│   ├── README.md
│   └── .github/workflows/gitascii.yml
└── gitascii branch
    ├── gitascii.json
    ├── gitascii_work.json              # example additional profile
    └── profiles/
        ├── default/{dark.svg,light.svg}
        └── work/{dark.svg,light.svg}

​

Editing, onboarding, and publication

1. Edit locally. The editor store updates the design and saves a browser draft. This does not itself publish a GitHub commit. Publish to GitHub sends the current widgets, styles, template, and slug as exportData to POST /api/github/commit.
2. Authenticate and authorize. GitHub OAuth exchanges an authorization code, reads the GitHub user, and establishes the GitAscii session. Repository publication separately uses a GitHub App installation token. The backend derives the owner from the session, checks profile write access, and stamps a revision. An absent installation returns not_installed with an installation URL; the editor redirects there and the setup callback returns to the app. That callback does not publish by itself.
3. Prepare the repository. The backend accesses username/username and discovers its default branch. On a 404, it attempts to create the profile repository using the installation token. A rejected creation request is returned as an error; successful repository creation is not guaranteed by this code path.
4. Render and commit now. GitAscii fetches fresh profile data and calls bootstrapGitasciiBranch. It creates gitascii if needed, renders both themes with the shared engine, processes external assets, and writes the configuration plus SVG pair through GitHub’s blobs/tree/commit/ref APIs. The branch ref update uses force: false.
5. Write integration files. The backend generates the README embed and .github/workflows/gitascii.yml on the default branch, updating each only when its content differs. These writes are separate from the SVG/config commit.
6. Request a refresh and persist app state. It sends workflow_dispatch for gitascii.yml with ref set to the default branch, then attempts to save the configuration in GitAscii storage. Dispatch and storage failures are logged without failing an otherwise completed publication. The editor marks its draft clean only after a successful response.

​

Pro profile mutations

​

What the backend and database retain

​

Workflow and Action refreshes

1. Reads the gitascii branch and discovers gitascii.json / gitascii_[slug].json configurations through GitHub’s tree/blob APIs. It does not load profile JSON from GitAscii’s database. Missing branches or no usable configurations fail the run; onboarding must create them first.
2. Checks the publication policy. Only scheduled runs apply the elapsed-time guard, measured against the latest branch commit date. The effective interval is the larger of refresh_minutes and the policy minimum. Without a successful OIDC policy response, the minimum falls back to 1,440 minutes; Pro’s supported minimum is 60. Manual dispatch bypasses this elapsed-time guard.
3. Fetches fresh GitHub data using REST and GraphQL, renders both themes for all discovered profiles (or the optional profile_slug selection), and inlines permitted external assets. See Rendering and the ASCII Pipeline for engine internals.
4. Checks that each result contains SVG markup and submits the generated SVGs together through publishAtomic. Matching Git blob hashes produce svg_unchanged; a changed branch head or applicable configuration revision produces skipped_stale. Otherwise it creates one commit and advances the branch with force: false.
5. Optionally reports profile-scoped health results with GitHub OIDC. Pro workflows grant id-token: write; see Health Monitoring and Telemetry & Privacy.

​

How the SVG reaches the README

https://raw.githubusercontent.com/USERNAME/USERNAME/gitascii/profiles/default/dark.svg
https://raw.githubusercontent.com/USERNAME/USERNAME/gitascii/profiles/default/light.svg

​

Failure and consistency boundaries

​

V1: verified historical rendering path

• Save: the publisher wrote configuration JSON to the profile repository’s default branch and saved an app-side copy. README embeds pointed to GitAscii HTTP SVG endpoints such as /api/[username], with theme/slug variants and cache-busting URLs in some paths. A separate contribution-snake workflow existed; it did not render the whole GitAscii profile.
• Render and serve: on an uncached HTTP request, GitAscii loaded configuration (memory/Redis/PostgreSQL, then legacy GitHub locations), fetched GitHub data, ran renderSvg, inlined external images, and returned image/svg+xml. Missing configuration could fall back to a template.
• Cache/proxy: the service had an optional Cloudflare Cache API layer, memory and compressed Redis SVG caches, in-flight request deduplication, ETags/304 responses, and browser/CDN cache headers. Normal responses requested a 300-second cache lifetime and CDN stale-while-revalidate; degraded results used shorter lifetimes. GitHub Camo added another cache/proxy boundary for README embeds.
• Limitation: cold generation still depended on the GitAscii runtime, cache/storage availability, GitHub requests, and external assets before the proxy received an image. The historical service explicitly records that awaiting an edge-cache write caused cold renders to reach Camo 504 timeouts. Layered invalidation and cache lifetimes also complicated update visibility.

​

V1 versus V2

​

V1 to V2 migration and backfill

1. A secret-protected POST /api/internal/migration reads eligible rows from PostgreSQL’s migration_installations table, mints installation tokens, checks rate limits, and records outcomes. Eligible states are pending, failed, permissions_missing, and post_merge_pending, with fewer than five attempts.
2. For an unmigrated repository, the engine loads the default profile through existing storage/fallbacks and fetches fresh GitHub data. If no configuration is found, it constructs a minimal stats configuration. It bootstraps gitascii and the initial SVG pair before proposing integration changes.
3. It opens a PR from gitascii-v2-migration to the default branch with the workflow and generated README. The PR also removes root gitascii.json / gitascii_default.json from the default branch when present. This migration handles the default profile; it is not an all-slug backfill.
4. When a workflow is already present, the engine checks the branch, both default SVGs, and the README raw URL. It may rewrite the README to repair the embed or dispatch a refresh. It returns completed only when those checks pass; otherwise it returns post_merge_pending. Existing open or closed-unmerged PRs have separate states.

​

Verification limits