# shyam-k/ddev-typo3-src architecture

> Architecture diagram of the GitHub repository shyam-k/ddev-typo3-src, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shyam-k/ddev-typo3-src
- Repository: https://github.com/shyam-k/ddev-typo3-src

## Overview

##### Project type + purpose (what you are diagramming)
This repo is **not an application codebase** in the classic sense (no `src/`, no custom backend/frontend). It’s an **infrastructure + bootstrap template** to spin up a **TYPO3 “legacy / without-composer” installation** locally using **DDEV (Docker-based)** and to install TYPO3 **from `get.typo3.org`** on first `ddev start`, using **symlinks** per TYPO3’s official “get and unpack” approach.

- **Local developer machine → DDEV orchestration → Docker containers**
- **Post-start hooks** that run the install script
- **TYPO3 runtime inside the web container** (PHP + webserver)
- **Database container** (MariaDB/MySQL configured in `.ddev/config.yaml`)
- **File layout + symlinked TYPO3 source** in/under `htdocs`
- **External dependency**: `get.typo3.org` (download source tarball/zip)
- Optional: **local extensions folder** (`packages` by default) mapped into the container

##### File structure analysis (what maps to components)
From the tree:

- `.ddev/config.yaml`
- The *control plane* of the project.
- Defines webroot (`htdocs`), PHP version, DB type/version.
- Contains **post-start hooks** (“doing the whole magic”) that trigger installation if TYPO3 isn’t already set up.
- Carries environment variables like `TYPO3_MAJOR_VERSION`, optionally `TYPO3_SRC_VERSION`, and `TYPO3_LOCAL_EXTENSIONS`.

- `bin/install-typo3`
- The bootstrapper / installer script invoked by DDEV hooks.
- Downloads TYPO3 source for the configured version and sets up symlinks and initial structure under `htdocs`.

- `htdocs/`
- Document root for the web container.
- Initially mostly empty (`.gitkeep`), later populated by the installer (including symlinks to the TYPO3 source distribution and generated runtime dirs).

No app code, no tests. The “logic” is in DDEV hooks + the installer script.

##### README-derived runtime behavior (key flows to show)
Critical behaviors mentioned explicitly:
- On `ddev start`, **if TYPO3 is not already setup**, the hooks run and install TYPO3.
- TYPO3 version selection:
- `TYPO3_MAJOR_VERSION` (default behavior per branch)
- or `TYPO3_SRC_VERSION` (pin exact release; overrides major)
- Default docroot is `htdocs` (can be changed in `.ddev/config.yaml`)
- Windows symlink constraints (developer mode/admin shell) — not a component, but note it as an annotation.
- Upgrade procedure relies on the same mechanism (change versions in config, restart, run TYPO3 upgrade wizard), and stresses DB export/import.

Optional feature:
- Local extensions via a host folder (default `packages`) mounted/available to TYPO3; configurable via `TYPO3_LOCAL_EXTENSIONS`.

##### Developer Workstation (Host OS)
- Repo working copy (`.ddev/`, `bin/`, `htdocs/`, optional `packages/`)
- DDEV CLI

##### DDEV / Docker Runtime (Orchestrator layer)
- DDEV project config (`.ddev/config.yaml`)
- Responsible for container lifecycle and hook execution

##### Web Container
- Webserver + PHP (version per config)
- TYPO3 runtime
- Mounted docroot: `htdocs/`

##### Database Container
- MariaDB or MySQL (version per config)
- Used by TYPO3 install tool and runtime

##### External TYPO3 Distribution Source
- `https://get.typo3.org`
- Download target for TYPO3 tarball/zip based on `TYPO3_MAJOR_VERSION`/`TYPO3_SRC_VERSION`

##### Browser (User Agent)
- Accesses the TYPO3 Install Tool and later the TYPO3 backend/frontend via DDEV routing

##### (Optional) Local Extensions Folder
- `packages/` on host (or custom folder)
- Consumed by TYPO3 as local extensions (composer-like)

**Lifecycle / orchestration**
- Developer → `ddev start` → DDEV orchestrates Docker containers
- DDEV → Web container: executes **post-start hooks**
- Post-start hook → `bin/install-typo3` (inside container context)

**Install-time download + filesystem wiring**
- `bin/install-typo3` → `get.typo3.org` (HTTP download)
- `bin/install-typo3` → `htdocs/` (extracts TYPO3 source + creates symlinks)
- Web container ↔ `htdocs/` (docroot mount; TYPO3 reads/writes runtime dirs)

**Runtime**
- Browser → Web container (HTTP)
- Web container ↔ DB container (SQL)
- TYPO3 runtime ↔ optional local extensions directory (reads extensions)

- Developer → `ddev export`/`ddev import` → DB container (backup/restore)
- Developer edits `.ddev/config.yaml` → changes PHP/DB/TYPO3 version → `ddev start` reruns hooks → TYPO3 upgrade wizard in browser

##### Architectural patterns/design principles used
For this repo, the notable patterns are:
- **Infrastructure-as-configuration**: `.ddev/config.yaml` is the single source of truth for runtime versions and hooks.
- **Idempotent bootstrap**: “install on first start if not already setup” (show a decision diamond: “TYPO3 already set up?”).
- **Separation of concerns**: web runtime vs database container; installer script separate from config.
- **Source-as-symlink pattern** (TYPO3 legacy style): application entry points under docroot link to a shared TYPO3 source directory.

##### Relevant technologies (label them explicitly)
- DDEV Local
- Docker
- DB: MariaDB/MySQL
- TYPO3 CMS (legacy “without composer”)
- External: get.typo3.org
- Host OS symlinks note (especially Windows)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================================================
    %% System Context (C4 L1)
    %% =========================================================
    Dev["Developer<br/>(Workstation)"]:::actor
    Browser["Browser<br/>(Install Tool / Backend / Frontend)"]:::actor
    GetTypo3["get.typo3.org<br/>(TYPO3 releases)"]:::external

    subgraph LocalDev["Local Dev Environment (DDEV + Docker)"]
        DdevCLI["DDEV CLI"]:::orchestrator
        DockerEngine["Docker Engine"]:::orchestrator

        subgraph DdevProject["DDEV Project (Repo working copy)"]
            RepoRoot["Repo root"]:::host
            Readme["README.md<br/>(usage + flow)"]:::doc

            subgraph ProjectFiles["Project Files"]
                DdevDir[".ddev/"]:::host
                DdevConfig[".ddev/config.yaml<br/>(webroot,PHP/DB,post-start hooks,<br/>TYPO3_MAJOR_VERSION / TYPO3_SRC_VERSION,<br/>TYPO3_LOCAL_EXTENSIONS)"]:::config

                BinDir["bin/"]:::host
                InstallScript["bin/install-typo3<br/>(bootstrap installer)"]:::script

                Htdocs["htdocs/<br/>(docroot volume mount)"]:::volume
                Gitkeep["htdocs/.gitkeep<br/>(pre-install placeholder)"]:::doc

                Packages["packages/<br/>(optional local extensions)"]:::volume
            end
        end

        subgraph DockerContainers["Docker Containers (DDEV project)"]
            WebC["web container<br/>(Webserver (DDEV default) + PHP)<br/>TYPO3 runtime"]:::container
            HookRunner["Post-start hook runner<br/>(from .ddev/config.yaml)"]:::orchestrator
            Decision{"TYPO3 already<br/>installed?"}:::decision
            Typo3Fs["TYPO3 legacy layout<br/>(symlinked source + entrypoints<br/>under htdocs/)"]:::typo3

            DbC[("db container<br/>(MariaDB/MySQL)")]:::database
        end
    end

    %% =========================================================
    %% Primary relationships
    %% =========================================================
    Dev -->|"runs ddev start"| DdevCLI
    DdevCLI -->|"controls"| DockerEngine
    DockerEngine -->|"starts"| WebC
    DockerEngine -->|"starts"| DbC

    Browser -->|"HTTP(S) via DDEV routing"| WebC
    WebC <-->|"SQL"| DbC

    %% Volumes / mounts
    WebC <-->|"mounts docroot"| Htdocs
    WebC <-->|"reads extensions (optional)"| Packages

    %% Hook + idempotent bootstrap
    DdevConfig -.->|"defines post-start hooks"| HookRunner
    HookRunner -.->|"executes in web container"| WebC
    WebC -.->|"on start"| Decision
    Decision -.->|"No"| InstallScript
    Decision -.->|"Yes"| Typo3Fs

    %% Installer actions
    InstallScript -.->|"downloads TYPO3 tarball/zip"| GetTypo3
    InstallScript -.->|"extracts + creates symlinks"| Htdocs
    Htdocs -->|"provides entrypoints + symlinked src"| Typo3Fs
    Typo3Fs -->|"served by"| WebC

    %% Docs linkage
    Readme -.->|"documents version selection + upgrade flow"| Dev
    Readme -.->|"describes first-start install"| Browser

    %% =========================================================
    %% Annotation / callout
    %% =========================================================
    SymlinkNote["Note: Symlinks required<br/>(Windows may need Developer Mode / admin shell)"]:::note
    Htdocs -.->|"symlink behavior"| SymlinkNote

    %% =========================================================
    %% Click events (from component_mapping)
    %% =========================================================
    click DdevConfig "https://github.com/shyam-k/ddev-typo3-src/blob/main/.ddev/config.yaml"
    click DdevDir "https://github.com/shyam-k/ddev-typo3-src/tree/main/.ddev/"
    click InstallScript "https://github.com/shyam-k/ddev-typo3-src/tree/main/bin/install-typo3"
    click BinDir "https://github.com/shyam-k/ddev-typo3-src/tree/main/bin/"
    click Htdocs "https://github.com/shyam-k/ddev-typo3-src/tree/main/htdocs/"
    click Gitkeep "https://github.com/shyam-k/ddev-typo3-src/blob/main/htdocs/.gitkeep"
    click Readme "https://github.com/shyam-k/ddev-typo3-src/blob/main/README.md"

    %% =========================================================
    %% Styles
    %% =========================================================
    classDef actor fill:#ECEFF1,stroke:#455A64,stroke-width:1.5px,color:#263238
    classDef orchestrator fill:#E3F2FD,stroke:#1565C0,stroke-width:1.5px,color:#0D47A1
    classDef container fill:#BBDEFB,stroke:#0D47A1,stroke-width:1.5px,color:#0D47A1
    classDef database fill:#C8E6C9,stroke:#1B5E20,stroke-width:1.5px,color:#1B5E20
    classDef external fill:#E1BEE7,stroke:#6A1B9A,stroke-width:1.5px,color:#4A148C
    classDef host fill:#F5F5F5,stroke:#616161,stroke-width:1.5px,color:#212121
    classDef config fill:#FFF9C4,stroke:#F9A825,stroke-width:1.5px,color:#5D4037
    classDef script fill:#FFE0B2,stroke:#EF6C00,stroke-width:1.5px,color:#4E342E
    classDef volume fill:#D7CCC8,stroke:#5D4037,stroke-width:1.5px,color:#3E2723
    classDef decision fill:#FFCDD2,stroke:#C62828,stroke-width:1.5px,color:#B71C1C
    classDef typo3 fill:#B2DFDB,stroke:#00695C,stroke-width:1.5px,color:#004D40
    classDef doc fill:#FFFFFF,stroke:#90A4AE,stroke-width:1.2px,color:#37474F
    classDef note fill:#FFF3E0,stroke:#FB8C00,stroke-width:1.2px,color:#E65100
```
