Danila KhodjaefandCursor
44d3d4359a
Covers architecture, setup, database schema, API reference, and image pipeline; link from README. Co-authored-by: Cursor <cursoragent@cursor.com>
89 lines
3.6 KiB
Markdown
89 lines
3.6 KiB
Markdown
# 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 |
|