Architecture

architecture_en.html

This document describes how the MyAnythingList system is built internally. It explains the startup model, parsing model, rendering model, state model, and deployment model. It is the technical companion to the behavioral truth defined in requirements_en.html.

1. High-Level System Model

The system can be understood as a sequence of transformations:

free-form UTF-8 text
→ URL discovery
→ comment / command parsing
→ tile model construction
→ thumbnail and QR resolution
→ grid rendering
→ interactive control state

The user does not need to learn a rigid playlist syntax first. The architecture exists to extract useful structure from ordinary text.

2. Startup Architecture

The top of the main application file follows a standardized architecture.

<meta charset="UTF-8" />
<title>generic fallback title</title>
<!-- Build: ... -->
<!-- Source files: ... -->

window.MyAnythingListConfig = { ... };

const BUILD_FILE = "...";
const ProjectSourceURL = "...";
const PageTitle = "...";
const HeaderText = `...`;
const FooterText = `...`;

• window.MyAnythingListConfig contains real startup/runtime values and URL-mirrored values.
• Branding/template strings are kept outside the config object.
• Header/footer visibility toggles remain runtime config values.
• Actual header/footer text is injected separately.
• Page title should be set from a startup variable so the same file can remain reusable.

3. Configuration and State Model

The runtime state model includes both startup defaults and current UI state.

Examples of state variables

• GRID
• QR_X, QR_Y, QR_SIZE
• ShowQR, ShowTypes, ShowURLs
• ShowHeaderText, ShowFooterText
• ShowControls, ShowGear, AutoHideGear
• Output_Resolution, Download_Format

GET variables may mirror supported startup values, but branding/template content should remain outside exported state objects where appropriate.

4. URL and Command Parsing Pipeline

The parsing system has multiple layers:

1. Read raw UTF-8 text.
2. Split into manageable textual units while preserving discovery order.
3. Detect valid URLs anywhere in the text.
4. Recognize comment lines beginning with #.
5. Recognize command lines beginning with #_.
6. Attach contextual commands to the most recent URL above them, unless the command creates standalone content.
7. Build a normalized internal tile list.

5. Command Interpreter Architecture

The command interpreter is a second semantic layer on top of comment parsing. It must support contextual augmentation of playlist items and, where needed, standalone non-URL panels.

Current and planned command categories

• Thumbnail replacement commands
• Image-only panel commands
• Future panel-behavior or presentation commands

Commands should remain readable in plain text and must not require hidden binary metadata.

6. Tile Model Architecture

Each discovered item becomes a tile model with content, presentation, and overlay metadata.

A tile may include:

• primary URL or image source
• resolved media type
• thumbnail source
• QR target URL
• type pill visibility state
• URL line visibility state
• clickability or informational-only status

7. Thumbnail Resolution Architecture

The thumbnail resolver determines what image to show for a tile.

command-defined thumbnail
→ uploaded thumbnail
→ platform-derived thumbnail
→ generic fallback

• YouTube and similar platforms may provide default thumbnails.
• Playlist commands may override those thumbnails.
• User-uploaded thumbnails must target the true tile image layer.
• QR image elements must never be confused with thumbnail image elements.

8. QR Architecture

QR generation is an overlay subsystem.

• It is driven by the tile’s link target.
• It has separate position and size parameters.
• It must bind correctly at startup, not only after subsequent UI changes.
• It must remain visually and logically separate from the thumbnail layer.

In image-only panel modes, the QR target may still point to the image URL unless the command semantics explicitly suppress link affordances.

Startup QR Geometry Rule

QR placement is a geometry-sensitive rendering pass. The architecture must treat first-paint placement as part of the real layout contract, not as a disposable placeholder.

• QR placement should be computed from stable tile dimensions and usable thumbnail area.
• A startup frame in which the QR appears in the wrong position and later snaps to the correct position is an architectural defect.
• If an additional post-render correction pass is still required, the visible result should be hidden or deferred until the first stable placement is known.
• Live rendering and export rendering should share the same placement model so that downloaded images resemble the visible tile.

9. Rendering Architecture

The rendering layer transforms tile models into grid panels.

tile model
→ tile container
→ thumbnail or image layer
→ QR overlay
→ footer overlays
→ click / info affordances

• The grid must remain legible across multiple aspect and resolution modes.
• Footer overlays such as type pill and URL line must stay above the base image layer unless intentionally suppressed.
• Image-only commands must still fit within the same rendering architecture.

URL Art Composition Model

URL art is a typographic tile mode whose composition depends on tile size, QR quadrant, and footer visibility state.

• The renderer should attempt best-fit scaling so the full URL remains visible inside the tile for ordinary and moderately long URLs.
• The text block should be composed in relation to the QR zone instead of being centered blindly.
• When the small footer URL is visible, the large URL-art text must remain visibly composed within the tile and should not be pushed beneath or behind the footer strip.
• When the small footer URL is hidden, the text composition may extend lower because the footer strip is no longer competing for readable space.
• Clipping is allowed only after reasonable fitting attempts fail for extreme URLs.

10. Control Panel and Gear Architecture

The control panel and gear are not separate unrelated features. They are part of a single recoverable control-state architecture.

• The gear is the entry/exit affordance for hidden controls.
• When controls are visible, the gear remains visible because it is the close affordance.
• Auto-hide logic applies to the gear only when controls are hidden and the gear is configured to exist.
• The gear hotzone must not obstruct normal button use in the control row.

11. Editor Architecture

The playlist editor is an in-browser editing environment for the raw text source.

• It must preserve ordinary free-form text use.
• It must avoid misleading instructions that falsely narrow the parser model.
• It must allow remote loading when CORS permits it.
• It must support local file loading and save/rebuild behavior.
• It should act as a direct textual authoring surface, not an opaque form builder.

12. Output and Export Architecture

Output generation is a secondary pipeline layered on top of tile rendering.

• Thumbnail exports use configurable output resolutions.
• Print-oriented targets such as cards and postcards are first-class use cases.
• State export should remain readable, compact where appropriate, and explicit where necessary.
• Large raw playlist text should not be forced into every exported state representation.

13. Documentation Architecture

The documentation tree is part of the project architecture, not an afterthought.

/_docs/
  index-docs.html
  /en/
    index_en.html
    requirements_en.html
    architecture_en.html
    system_en.html
    developer_en.html
    vision_en.html

• The docs are meant to be browsable, inspectable, and mirror-friendly.
• Language folders are the stable translation structure.
• English acts as the canonical source language for translation.
• Docs should be rich enough to replace dependence on old chat sessions.

Request-to-Documentation Propagation Rule

The documentation architecture is expected to absorb new requirements during development sessions. A user request that changes behavior, clarifies intended output, or defines a new regression boundary should be reflected in the relevant canonical document rather than left only in chat history.

14. Hosting Architecture

The system is intentionally designed to support static or mostly static deployment.

authoring / mastering environment
→ generated files
→ static hosting (Apache, S3, CDN)
→ public consumption

• A VPS may be used for mastering, generation, and automation.
• Public delivery may move to S3 + CDN style serving.
• Generated folder indexes can replace server-side directory-listing dependence where appropriate.
• Static delivery reduces request-time CPU overhead and improves scalability.

15. Build and Archive Architecture

Dated build archives may exist under daily build folders and are useful for transparency, testing, and human historical review.

• Daily builds belong inside dated archive folders.
• Historical chat logs may be kept as HTML archives.
• These historical materials are not the canonical spec.
• The canonical spec belongs in the documentation tree.

16. Architectural Principle

For binding functional truth, read requirements_en.html. For philosophical purpose, read vision_en.html.