Add project documentation under Documentation/.

Covers architecture, setup, database schema, API reference, and image pipeline; link from README. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-19 09:46:44 +03:00
parent 40db99d734
commit 44d3d4359a
6 changed files with 577 additions and 0 deletions
@@ -0,0 +1,88 @@
+# 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 |