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.

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.

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.

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.

v09 Delta — Layout Geometry Clarifications

The viewport fitting system now has three logical modes: Fit Width, Fit Height, and Fit Everything. Safe-area profiles modify the usable viewport rectangle before scale is computed. Digital safe areas are intentionally tiny; Tube TV safe areas are intentionally generous. Fit Everything must use a single uniform scale derived from the usable viewport bounds. The immutable tile layer order remains: thumbnail or URL art, QR, type pill, small URL, optional overlays.

Updated: 2026-03-12 v09

v10 Delta — Fixed Tile Composition and Startup Discipline

Tile composition remains deterministic. Thumbnail imagery or URL art renders as the texture/background thumbnail layer. The QR code renders only on its dedicated QR layer above thumbnail imagery and below the pill and smaller URL text. The QR payload must use the full valid URL including anchor-comment fragments.

Startup QR placement must be computed from final tile geometry. If geometry is not ready, the QR waits for final placement rather than flashing on an incorrect layer or position. This rule exists to prevent regressions where a later build accidentally loses the startup fix from an earlier build.

URL art should occupy as much readable thumbnail area as possible while staying visually larger than the footer URL text. Exports must preserve the same proportions, positioning, and scaling that appear on-screen.

v15 Delta — Canonical Build Filename and Alias Separation

For architecture and operations, the canonical daily build artifact should be stored under the dated filename index_beta_YYYY-MM-DD-vNN.html. Example: index_beta_2026-03-21-v01.html.

This file is the authoritative traceable artifact. A plain index.html may still be emitted as the public or local convenience alias, but that alias is not sufficient by itself for archive integrity, regression comparison, or handoff clarity.

Updated: 2026-03-21 v15

v14 Delta — Educational Mission, Transparency, and Misuse Resistance

MyAnythingList is a public educational system intended to help ethical, curious, and globally diverse people learn how information can be structured, inspected, rendered, and shared. The project should favor transparency, inspectability, multilingual access, and source-aware communication over black-box presentation.

• Open documentation, visible runtime logs, and educational commentary in code are intentional safeguards.
• The system should encourage understanding, attribution, and critical inspection rather than manipulative opacity.
• Language support should treat world language communities equitably, including both LTR and RTL interfaces.
• The project should be designed so good-faith users can learn it quickly and adapt it responsibly.
• No documentation update should erase the project’s educational and civilizational purpose.

Updated: 2026-03-21 v15