# luke-keaweb/archway architecture

> Architecture diagram of the GitHub repository luke-keaweb/archway, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/luke-keaweb/archway
- Repository: https://github.com/luke-keaweb/archway

## Overview

##### Project type and purpose
- This is a PHP‑based full‑stack web application.
- Purpose: Provide a frontend search UI that queries Archives NZ backend APIs, caches certain lookups in a local MySQL database, and renders results with custom templates and assets.

##### File structure
- Top‑level:
- .env.example / composer.json → environment and dependency management
- classes/ → all core PHP classes (Router, controllers, services, templates)
- functions.php → shared helper functions
- public/ → document root: index.php, CSS/JS assets, HTAccess
- html/ → static example pages
- Notice the public/index.php entry point uses classes/Router.class.php to dispatch routes to controller classes.
- Persistence: MySQL (SQL import), plus a local cache folder and cookie.txt for file‑system caching.

##### README for additional insights
- Routes: defined in Router → call methods on classes like AimsSearch, Entity, etc.
- AimsSearch calls external Archives NZ API (JSON) → parsed by ResultParser → formatted with FormatData.
- Series, Agency, Flickr classes perform DB lookups to avoid repeated network calls.
- DefaultTemplate handles HTML skeleton; custom templates can be injected via .env.

##### Details to capture
- Entry point: public/index.php + .htaccess rewrite
- Routing logic in classes/Router.class.php
- Controller classes and their responsibilities (AimsSearch, Entity, FormElements, etc.)
- Data flow:
- JSON from Archives NZ → ResultParser → FormatData
- Series/Agency lookups → MySQL
- Template injection via DefaultTemplate and .env overrides
- Static assets served directly from public/assets

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["Client Browser"]:::frontend

    subgraph "Public Layer"
        Apache["Apache2 + PHP-FPM"]:::server
        HTAccess["public/.htaccess"]:::server
        Index["public/index.php"]:::server
    end

    subgraph "Application Layer"
        Router["Router"]:::server
        Helpers["functions.php"]:::server
        subgraph "Controllers & Services"
            AimsSearch["AimsSearch"]:::server
            Entity["Entity"]:::server
            FormElements["FormElements"]:::server
            Series["Series"]:::server
            Agency["Agency"]:::server
            Flickr["Flickr"]:::server
            ResultParser["ResultParser"]:::server
            FormatData["FormatData"]:::server
        end
        Template["DefaultTemplate"]:::server
    end

    subgraph "Storage Layer"
        MySQL["MySQL Database"]:::storage
        FileCache["File Cache & cookie.txt"]:::storage
    end

    Archives["Archives NZ API"]:::external
    Assets["public/assets (CSS/JS/images)"]:::frontend
    StaticPages["html/"]:::frontend
    EnvExample[".env.example"]:::server
    Composer["composer.json"]:::server
    ComposerLock["composer.lock"]:::server

    Browser -->|"HTTP Request"| Apache
    Apache -->|"Rewrite"| HTAccess
    HTAccess -->|"Entry Point"| Index
    Index -->|"Dispatch"| Router
    Router -->|"uses"| Helpers
    Router -->|"routes to"| AimsSearch
    Router -->|"routes to"| Entity
    Router -->|"routes to"| FormElements
    Router -->|"routes to"| Series
    Router -->|"routes to"| Agency
    Router -->|"routes to"| Flickr

    AimsSearch -->|"calls"| Archives
    AimsSearch -->|"caches via"| FileCache
    Series -->|"lookup"| MySQL
    Series -->|"caches via"| FileCache
    Agency -->|"lookup"| MySQL
    Agency -->|"caches via"| FileCache
    Flickr -->|"caches via"| FileCache

    AimsSearch --> ResultParser
    ResultParser --> FormatData
    FormatData --> Template
    Template -->|"renders HTML"| Browser
    Browser --> Assets

    classDef frontend fill:#ADD8E6,stroke:#000
    classDef server fill:#90EE90,stroke:#000
    classDef storage fill:#FFD580,stroke:#000
    classDef external fill:#FFB6C1,stroke:#000

    click Router "https://github.com/luke-keaweb/archway/blob/main/classes/Router.class.php"
    click AimsSearch "https://github.com/luke-keaweb/archway/blob/main/classes/AimsSearch.class.php"
    click Entity "https://github.com/luke-keaweb/archway/blob/main/classes/Entity.class.php"
    click FormElements "https://github.com/luke-keaweb/archway/blob/main/classes/FormElements.class.php"
    click Series "https://github.com/luke-keaweb/archway/blob/main/classes/Series.class.php"
    click Agency "https://github.com/luke-keaweb/archway/blob/main/classes/Agency.class.php"
    click Flickr "https://github.com/luke-keaweb/archway/blob/main/classes/Flickr.class.php"
    click ResultParser "https://github.com/luke-keaweb/archway/blob/main/classes/ResultParser.class.php"
    click FormatData "https://github.com/luke-keaweb/archway/blob/main/classes/FormatData.class.php"
    click Template "https://github.com/luke-keaweb/archway/blob/main/classes/DefaultTemplate.class.php"
    click Helpers "https://github.com/luke-keaweb/archway/blob/main/functions.php"
    click Index "https://github.com/luke-keaweb/archway/blob/main/public/index.php"
    click HTAccess "https://github.com/luke-keaweb/archway/blob/main/public/.htaccess"
    click Assets "https://github.com/luke-keaweb/archway/tree/main/public/assets/"
    click StaticPages "https://github.com/luke-keaweb/archway/tree/main/html/"
    click EnvExample "https://github.com/luke-keaweb/archway/blob/main/.env.example"
    click Composer "https://github.com/luke-keaweb/archway/blob/main/composer.json"
    click ComposerLock "https://github.com/luke-keaweb/archway/blob/main/composer.lock"
```
