Skip to content

docs: #48 README and AI usage log reflect what has landed #49

Merged
merged 3 commits into from
Oct 16, 2026
+107 −55
Merged

docs: #48 README and AI usage log reflect what has landed #49

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
63693d8
docs: #48 README and AI usage log reflect what has landed
erikhfj Oct 15, 2026
3a0ba67
docs: #48 fold in what #46 landed
erikhfj Oct 15, 2026
8f36881
docs: #48 log the #46 follow-up work
erikhfj Oct 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 69 additions & 26 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,22 +9,39 @@ wantlist ("crate").
IT2810 (NTNU) Project 2. Group T19: `erikhfj`, `robertky`, `evenkkl`,
`rachelks`.

| | |
| ----------------- | --------------------------------------- |
| Current milestone | **M1 - spec and mockup**, due 2 October |
| Live prototype | http://it2810-19.idi.ntnu.no/project2 |
| Workflow | [`docs/WORKFLOW.md`](docs/WORKFLOW.md) |
| AI usage log | [`docs/AI-USAGE.md`](docs/AI-USAGE.md) |
| | |
| ----------------- | --------------------------------------------------------- |
| Current milestone | **M2 - PostgreSQL and GraphQL on the VM**, due 16 October |
| Live prototype | http://it2810-19.idi.ntnu.no/project2 |
| Workflow | [`docs/WORKFLOW.md`](docs/WORKFLOW.md) |
| AI usage log | [`docs/AI-USAGE.md`](docs/AI-USAGE.md) |
| Running on the VM | [`docs/VM-setup.md`](docs/VM-setup.md) |

## Getting started

Requires Node.js 24+ and [pnpm](https://pnpm.io) 10+.

```bash
pnpm install
pnpm dev # Vite dev server on :5173
pnpm dev # Vite dev server on :5173
```

To also run the API locally you need PostgreSQL and a `DATABASE_URL` in
`server/.env`:

```bash
pnpm --filter @t19/server db:migrate # create the catalog tables
pnpm --filter @t19/server db:seed # optional: replace the catalog with the sample albums
pnpm --filter @t19/server dev # GraphQL Yoga on :3001/graphql
```

`db:seed` is a reset command, not a loader. It replaces the catalog and,
through foreign-key cascades, deletes the reviews and crate items hanging
off it. Do not run it against a database holding user content you want.

`docs/VM-setup.md` has the same steps for the group VM, plus a smoke suite
to check a deployment.

Before opening a PR:

```bash
Expand All @@ -33,26 +50,47 @@ pnpm format:check && pnpm lint && pnpm typecheck && pnpm test

All four must pass. CI runs the same thing.

| Command | Purpose |
| ----------------------------------- | ---------------------------------- |
| `pnpm dev` | Vite dev server |
| `pnpm build` | Type-check + production build |
| `pnpm lint` | ESLint - must pass with 0 warnings |
| `pnpm format` / `pnpm format:check` | Prettier |
| `pnpm typecheck` | `tsc --noEmit` in every workspace |
| `pnpm test` | Vitest, single run |
| Command | Purpose |
| -------------------------------------- | ---------------------------------------------- |
| `pnpm dev` | Vite dev server, client only |
| `pnpm build` | Type-check + production build, every workspace |
| `pnpm lint` | ESLint - must pass with 0 warnings |
| `pnpm format` / `pnpm format:check` | Prettier |
| `pnpm typecheck` | `tsc --noEmit` in every workspace |
| `pnpm test` | Vitest, single run |
| `pnpm --filter @t19/server dev` | GraphQL API on `:3001/graphql` |
| `pnpm --filter @t19/server db:migrate` | Apply the Drizzle migrations |
| `pnpm --filter @t19/server db:seed` | Load the sample catalog |

## Project status

| Milestone | Due | Delivers |
| --------- | ------ | ----------------------------------------------------------------------------------------- |
| M1 | 2 Oct | Spec and mockup: GraphQL schema, architecture ADRs, UI sketch, client rendering mock data |
| M2 | 16 Oct | PostgreSQL + GraphQL backend on the VM, client interaction |
| M3 | 30 Oct | Beta: search, paging, sorting, filtering, accessibility, bærekraft |
| M4 | 13 Nov | Finished prototype and the full test suite |

`client/` currently renders mock data. `server/` (PostgreSQL + GraphQL Yoga)
arrives in M2 and `e2e/` (Playwright) in M4.
| Milestone | Due | Delivers |
| --------- | ------ | ----------------------------------------------------------------------------------------------------- |
| M1 | 2 Oct | Spec and mockup: GraphQL schema, data model, architecture ADRs, UI specification, workflow and AI log |
| M2 | 16 Oct | PostgreSQL + GraphQL backend on the VM, client interaction |
| M3 | 30 Oct | Beta: search, paging, sorting, filtering, accessibility, bærekraft |
| M4 | 13 Nov | Finished prototype and the full test suite |

### Where the code is

| Path | What it is |
| ---------------- | --------------------------------------------------------------------------------------------------------------- |
| `client/` | React + Vite. Still the M1 skeleton; #9 wires the search view to the API |
| `server/` | GraphQL Yoga + Drizzle over PostgreSQL. `searchAlbums` with filtering, facets and keyset paging. Live on the VM |
| `schema.graphql` | The contract both sides work against |
| `docs/` | Architecture and data model ADRs, UI specification, workflow, AI log, VM runbook |

Implemented: the PostgreSQL schema, with tracks, simulated users, reviews
and crate items, and trigger-maintained full-text search over titles
(weight A) and artist names (weight B). On top of it, album search by word,
genre and decade facets, keyset paging, four sort modes, and the `X-User-Id`
contract for the simulated user.

Planned: filters and sorting in the UI, the reviews and wantlist
mutations, accessibility and bærekraft (M3), then the Playwright `e2e/`
suite (M4). The GraphQL operations behind those are in `schema.graphql`,
but `searchAlbums` is the only query with a resolver so far, along with the
`Album` fields it returns.

## Infrastructure

Expand All @@ -61,8 +99,13 @@ containers and not on an external service. Live at
<http://it2810-19.idi.ntnu.no/project2>, GraphQL on port 3001 behind an
Apache `ProxyPass`. PostgreSQL is local to the machine and is not exposed.

CI runs on a self-hosted runner on the same VM. Pushes to `main` build the
client and publish it to Apache.
The API is a systemd unit, `crate-api.service`, running the built `server/`
from `~/T19-Project-2`. It loads `DATABASE_URL` from that checkout's
`.env`, which is gitignored and so survives a deploy.

CI runs on a self-hosted runner on the same VM. Pushes to `main` run the
quality gates, then deploy the client bundle to Apache and the built API to
the checkout `crate-api` runs from.

## Working in this repository

Expand Down
Loading