English Docs Index Choose Language Browse This Folder Browse Docs Root

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 = `...`;

3. Configuration and State Model

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

Examples of state variables

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.

The architecture is deliberately more flexible than a line-oriented parser. The parser is a text interpreter, not merely a one-line tokenizer.

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

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:

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

8. QR Architecture

QR generation is an overlay subsystem.

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

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.

11. Editor Architecture

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

12. Output and Export Architecture

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

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

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

15. Build and Archive Architecture

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

16. Architectural Principle

The architecture of MyAnythingList is designed to preserve human-readable text, visual usefulness, static deployability, and future maintainability at the same time. Its strength is not just what it renders, but how understandable the whole pipeline remains.

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

Runtime Layout Geometry and Layer Stack

Fixed tile composition order

Every tile must be built in a deterministic order: thumbnail layer first, QR layer second, type pill layer third, small URL layer fourth, and any optional top text overlays above those. URL Art belongs to the thumbnail layer and is therefore treated exactly like any other thumbnail source.

The QR layer is never allowed to migrate into the background thumbnail path during startup, export, or thumbnail download generation. The QR layer is rendered only after tile geometry is known and must remain above all thumbnail imagery.

Visible-first wall construction

The wall may stage the first visible tiles for immediate paint and append the remaining off-screen tiles afterward, but the visible-first frame must already have correct QR placement and correct overlay ordering. First paint correctness is mandatory and later snapping is considered a regression.

Viewport scaling model

Viewport scaling is controlled by two first-class runtime properties: ViewScaleMode and SafeAreaProfile. The system must calculate a usable wall viewport by subtracting the active safe-area insets plus the header, controls, footer, and margins from the window bounds. Fit modes then scale within that usable viewport.