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,103 @@
+# Art Gallery — setup and operations
+
+## Prerequisites
+
+- **Node.js** 20+
+- **PostgreSQL** reachable from the app host
+- Network access to Wikipedia / Wikimedia (only for seeding and on-demand image fetch)
+
+## Environment
+
+Copy the example file and fill in credentials:
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Description |
+|----------|-------------|
+| `DB_HOST` | PostgreSQL host |
+| `DB_PORT` | Port (default `5432`) |
+| `DB_USER` | Database user |
+| `DB_PASSWORD` | Database password |
+| `DB_NAME` | Database name (`Gallery`) |
+| `PORT` | API listen port (default `3001`) |
+| `IMAGE_DIR` | Root for cached images (default `./data/images`) |
+
+`.env` is git-ignored; never commit passwords.
+
+## Install
+
+```bash
+npm install
+cd client && npm install && cd ..
+```
+
+## Database bootstrap
+
+One-shot setup (migrate + seed):
+
+```bash
+npm run setup
+```
+
+Or step by step:
+
+```bash
+npm run migrate    # apply db/schema.sql
+npm run seed       # eras, movements, artists, paintings, influences
+```
+
+If migration fails with permission errors, grant schema rights to the app user first (see [DB_structure.md](DB_structure.md)).
+
+## Run
+
+| Command | Purpose |
+|---------|---------|
+| `npm run server` | API + static SPA on `PORT` |
+| `npm run dev:server` | API with nodemon reload |
+| `npm run dev:client` | Vite dev server on :5173 |
+| `npm run dev` | Alias for `server` |
+
+**Production frontend:** build the client, then start the server:
+
+```bash
+cd client && npm run build && cd ..
+npm run server
+```
+
+Open http://localhost:3001 (or your configured `PORT`).
+
+## Maintenance scripts
+
+| Script | Command | Purpose |
+|--------|---------|---------|
+| Seed | `npm run seed` | Reload curated Wikipedia data |
+| Thumbnails migration | `npm run migrate:thumbnails` | Add thumbnail columns |
+| Fetch missing images | `npm run fetch-images` | Backfill painting files |
+| Fetch artist portraits | `npm run fetch-artist-images` | Backfill portrait files |
+| Sync image paths | `npm run sync-image-paths` | Align DB paths with disk |
+| Expand catalog | `npm run expand-catalog` | Add paintings from Wikipedia lists |
+| Update influences | `npm run update-influences` | Refresh influence edges |
+
+Scripts under `scripts/` that are not yet present locally may need to be restored from git history or re-added; core paths (`seed-wikipedia.js`, `image-fetcher.js`) are in the repository.
+
+## Remote repository
+
+Gitea: [Danilka/Art-gallery](https://gitea.mysuperlab.netcraze.pro/Danilka/Art-gallery)
+
+```bash
+git clone https://gitea.mysuperlab.netcraze.pro/Danilka/Art-gallery.git
+```
+
+After clone: copy `.env.example` → `.env`, install dependencies, run `npm run setup` against your Postgres instance.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| Empty timeline | DB not seeded | `npm run seed` |
+| 500 on all `/api/*` | Wrong `.env` or Postgres down | Check connection, logs |
+| Black frames in 3D gallery | No local image for painting | `POST …/preload-images` or `npm run fetch-images` |
+| Default Vite page instead of gallery | `client/dist` missing or stale | `cd client && npm run build` |
+| Permission denied creating tables | `gallery` user lacks CREATE | Run admin grants, then migrate |