# Art Gallery — architecture basics

Interactive virtual museum spanning art history: zoomable timeline, movement bands, 3D gallery halls, and painting influence graphs. See [README.md](../README.md) for quick start.

## Concept

The app is organised as a **drill-down hierarchy**:

1. **Timeline** — historical eras (Ancient → Contemporary) with definite or fuzzy date boundaries.
2. **Movement bands** — art movements aligned to the same time axis, each showing portrait thumbnails of key artists.
3. **3D gallery** — classic hall environment; paintings grouped by the artist’s creative periods.
4. **Painting detail** — full work in the centre, *Influenced By* on the left, *Influenced* on the right, link to artist biography.

All artwork images are stored locally under `data/images/` — the UI never hot-links to Wikipedia or Commons at runtime (except optional on-demand fetch when a file is missing).

## Stack

| Layer | Choice | Role |
|--------|--------|------|
| API | **Node.js + Express 5** | REST API, static image serving, optional SPA hosting from `client/dist` |
| Database | **PostgreSQL** | Eras, movements, artists, paintings, influence edges |
| Frontend | **React 19 + Vite 8** | SPA routing and UI |
| 3D | **Three.js** via `@react-three/fiber`, `@react-three/drei` | Virtual gallery navigation |
| Data ingestion | Node scripts | Wikipedia summaries, Commons images, curated influence data |

## Repository layout

```text
Gallery/
├── server/              # Express API, DB pool, image service
├── client/              # React/Vite frontend
│   ├── src/             # Source (components, pages, 3D scene)
│   └── dist/            # Production build (served by API when present)
├── scripts/             # Seed, image fetch, catalog expansion
├── data/images/         # Local portraits and paintings (+ thumbs/)
├── db/                  # SQL schema and migrations (when present)
├── Documentation/       # This folder
└── .env                 # DB and port config (not committed)
```

## Runtime modes

### Production-style (single process)

```bash
npm run server    # http://localhost:3001
```

Serves `/api/*`, `/images/*`, and the built SPA from `client/dist` if it exists.

### Development (two processes)

```bash
npm run dev:server   # API on :3001
npm run dev:client   # Vite on :5173, proxies /api and /images
```

Use the Vite URL during frontend work for HMR.

## User navigation flow

```mermaid
flowchart TD
  A[Home — timeline + movements] -->|scroll / drag / zoom| A
  A -->|click portrait| B[Artist bio]
  B -->|Enter Gallery| C[3D hall]
  C -->|click painting| D[Painting detail + influences]
  D -->|thumbnail left/right| D
  D -->|artist link| B
  B -->|Back| A
  C -->|Back| A
```

## Key design decisions

- **Timeline bounds** derive from the earliest art movement start year, not ancient-era metadata alone, so the default view opens where catalogued content begins.
- **Movement filtering** on zoom only shows movements that have at least one artist active in the visible year range.
- **3D gallery images** use locally cached files only (`galleryImageUrl`); slow remote fetches would break realtime rendering.
- **Influence data** is stored as directed edges between paintings, with optional citation fields (source author, quote, URL) for art-historical references.

## Related docs

| Document | Contents |
|----------|----------|
| [setup.md](setup.md) | Install, database, npm scripts |
| [DB_structure.md](DB_structure.md) | Tables and relationships |
| [API.md](API.md) | REST endpoints |
| [data-and-images.md](data-and-images.md) | Image pipeline and seeding |