# sseraflm/blue-rose-archive architecture

> Architecture diagram of the GitHub repository sseraflm/blue-rose-archive, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sseraflm/blue-rose-archive
- Repository: https://github.com/sseraflm/blue-rose-archive

## Overview

Blue Rose Archive is a song discography and credits archive. Editors add structured song and cover information to a hand-maintained JSON source, then a CLI sync upserts it into MariaDB. Visitors browse the catalogue, inspect song details, and use live search; those public pages read from the database. The graph includes the shared PDO layer and the documented relational schema. The README supports the overall workflow, while sampled source confirms the specific page queries and JSON/database operations; unsampled implementation details are not inferred.

Main entry points: [`src/db.php`](https://github.com/sseraflm/blue-rose-archive/blob/main/src/db.php) (PDO connection), [`tools/sync.php`](https://github.com/sseraflm/blue-rose-archive/blob/main/tools/sync.php) (Data sync), [`public/index.php`](https://github.com/sseraflm/blue-rose-archive/blob/main/public/index.php) (Catalogue page), [`public/api/search.php`](https://github.com/sseraflm/blue-rose-archive/blob/main/public/api/search.php) (Search API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Song authoring"]
  node_editor["Local editor<br/>[add-song.php]"]
  node_source_data["Song source<br/>[songs.json]"]
  node_sync["Data sync<br/>[sync.php]"]
end

subgraph group_public["Public archive"]
  node_catalogue["Catalogue page<br/>[index.php]"]
  node_search_ui["Live search<br/>[search.js]"]
  node_search_api["Search API<br/>[search.php]"]
  node_song_page["Song detail<br/>[song.php]"]
end

subgraph group_storage["Persistence"]
  node_pdo["PDO connection<br/>[db.php]"]
  node_schema["Archive schema<br/>[schema.sql]"]
  node_mariadb[("MariaDB")]
end

node_visitor(("Visitor"))

node_editor -->|"appends entries"| node_source_data
node_sync -->|"reads entries"| node_source_data
node_sync -->|"loads connection"| node_pdo
node_sync -->|"upserts songs"| node_mariadb
node_visitor -->|"opens catalogue"| node_catalogue
node_catalogue -->|"loads connection"| node_pdo
node_catalogue -->|"queries catalogue"| node_mariadb
node_visitor -->|"types query"| node_search_ui
node_search_ui -->|"requests matches"| node_search_api
node_search_api -->|"loads connection"| node_pdo
node_search_api -->|"searches titles"| node_mariadb
node_visitor -->|"opens song"| node_song_page
node_song_page -->|"loads connection"| node_pdo
node_song_page -->|"reads song data"| node_mariadb
node_pdo -->|"opens PDO session"| node_mariadb
node_schema -->|"defines tables"| node_mariadb

click node_editor "https://github.com/sseraflm/blue-rose-archive/blob/main/tools/add-song.php"
click node_source_data "https://github.com/sseraflm/blue-rose-archive/blob/main/data/songs.json"
click node_sync "https://github.com/sseraflm/blue-rose-archive/blob/main/tools/sync.php"
click node_catalogue "https://github.com/sseraflm/blue-rose-archive/blob/main/public/index.php"
click node_search_ui "https://github.com/sseraflm/blue-rose-archive/blob/main/public/js/search.js"
click node_search_api "https://github.com/sseraflm/blue-rose-archive/blob/main/public/api/search.php"
click node_song_page "https://github.com/sseraflm/blue-rose-archive/blob/main/public/song.php"
click node_pdo "https://github.com/sseraflm/blue-rose-archive/blob/main/src/db.php"
click node_schema "https://github.com/sseraflm/blue-rose-archive/blob/main/database/schema.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_editor,node_source_data,node_sync toneBlue
class node_catalogue,node_search_ui,node_search_api,node_song_page toneAmber
class node_pdo,node_schema,node_mariadb toneMint
class node_visitor toneIndigo
```

## Components

### Song authoring

- [Local editor](https://github.com/sseraflm/blue-rose-archive/blob/main/tools/add-song.php): `tools/add-song.php`
- [Song source](https://github.com/sseraflm/blue-rose-archive/blob/main/data/songs.json): `data/songs.json`
- [Data sync](https://github.com/sseraflm/blue-rose-archive/blob/main/tools/sync.php): `tools/sync.php`

### Public archive

- [Catalogue page](https://github.com/sseraflm/blue-rose-archive/blob/main/public/index.php): `public/index.php`
- [Live search](https://github.com/sseraflm/blue-rose-archive/blob/main/public/js/search.js): `public/js/search.js`
- [Search API](https://github.com/sseraflm/blue-rose-archive/blob/main/public/api/search.php): `public/api/search.php`
- [Song detail](https://github.com/sseraflm/blue-rose-archive/blob/main/public/song.php): `public/song.php`

### Persistence

- [PDO connection](https://github.com/sseraflm/blue-rose-archive/blob/main/src/db.php): `src/db.php`
- [Archive schema](https://github.com/sseraflm/blue-rose-archive/blob/main/database/schema.sql): `database/schema.sql`
- **MariaDB**

### Other components

- **Visitor**

## Connections

- Local editor → Song source: appends entries (evidence: `README.md`)
- Data sync → Song source: reads entries (evidence: `tools/sync.php`)
- Data sync → PDO connection: loads connection (evidence: `tools/sync.php`)
- Data sync → MariaDB: upserts songs (evidence: `tools/sync.php`)
- Visitor → Catalogue page: opens catalogue (evidence: `README.md`)
- Catalogue page → PDO connection: loads connection (evidence: `public/index.php`)
- Catalogue page → MariaDB: queries catalogue (evidence: `public/index.php`)
- Visitor → Live search: types query (evidence: `public/js/search.js`)
- Live search → Search API: requests matches (evidence: `public/js/search.js`)
- Search API → PDO connection: loads connection (evidence: `public/api/search.php`)
- Search API → MariaDB: searches titles (evidence: `public/api/search.php`)
- Visitor → Song detail: opens song (evidence: `README.md`)
- Song detail → PDO connection: loads connection (evidence: `public/song.php`)
- Song detail → MariaDB: reads song data (evidence: `public/song.php`)
- PDO connection → MariaDB: opens PDO session (evidence: `src/db.php`)
- Archive schema → MariaDB: defines tables (evidence: `README.md`)