Merge pull request #1159 from nowcommunity/codex/docs-entity-models-723

Add people and museum entity documentation

documentation/README.md

@@ -54,7 +54,10 @@ This folder is the canonical home for repository documentation.
 - [`devops/setup.md`](devops/setup.md)
 - [`devops/write-guard.md`](devops/write-guard.md)
 - [`entities/locality.md`](entities/locality.md)
+- [`entities/README.md`](entities/README.md)
+- [`entities/museum.md`](entities/museum.md)
 - [`entities/occurrence.md`](entities/occurrence.md)
+- [`entities/people.md`](entities/people.md)
 - [`entities/project.md`](entities/project.md)
 - [`entities/reference.md`](entities/reference.md)
 - [`entities/reference_types.md`](entities/reference_types.md)

documentation/entities/README.md

@@ -0,0 +1,32 @@
+# Entity Documentation
+
+This folder documents the main domain entities used by NOW Database. The goal is to keep a short, practical map of how each user-facing concept relates to Prisma models, API routes, and common frontend usage.
+
+## Primary entities
+
+- [Localities](locality.md): locality records, dating methods, age fields, coordinates, and locality tabs.
+- [Species](species.md): taxonomy records, required taxonomy fields, and species synonyms.
+- [Occurrences](occurrence.md): locality-species relationships and occurrence-specific editable fields.
+- [References](reference.md): reference records, reference types, authors, journals, and entity-reference links.
+- [Time Units](time_unit.md): named geologic time units and sequence/rank data.
+- [Time Bounds](time_bound.md): lower and upper bounds used by time units and locality dating.
+
+## Supporting entities
+
+- [Museums](museum.md): museum lookup records and locality-museum links.
+- [People](people.md): person records, optional user accounts, roles, and coordinator/contact links.
+- [Projects](project.md): projects, project contacts, project people, and locality/project links.
+- [Regions](region.md): named regions, countries, and coordinators.
+- [Reference Types](reference_types.md): available reference type definitions.
+
+## Coverage notes
+
+The Prisma schema also contains lower-level join, update-log, synonym, and lookup tables. Those should usually be documented inside the closest user-facing entity page unless they become independently editable in the UI.
+
+When adding an entity page, include:
+
+- the main Prisma model/table name
+- important relation tables
+- the routes used by the UI
+- the permission model, if it differs from the default authenticated read/edit flow
+- any known implementation caveats that would help the next change

documentation/entities/museum.md

@@ -0,0 +1,44 @@
+# Museums
+
+Museums are institution lookup records that can be linked to localities. The museum record itself describes the institution; the locality tab stores which museums are connected to a locality.
+
+## Database model
+
+The main museum lookup record is `com_mlist`:
+
+- `museum` (primary key, museum code)
+- `institution`
+- `alt_int_name`
+- `city`
+- `state_code`
+- `state`
+- `country`
+- `used_morph`
+- `used_now`
+- `used_gene`
+
+Locality links are stored in `now_mus`:
+
+- `lid` references `now_loc.lid`
+- `museum` references `com_mlist.museum`
+- composite primary key: `lid` + `museum`
+
+Deleting a locality cascades its `now_mus` rows. Deleting or renaming a museum code needs care because the code is part of the link-table key.
+
+## API endpoints
+
+- `GET /museum/all`: list museums
+- `GET /museum/:id`: read museum details and linked localities
+- `PUT /museum`: create or update a museum; requires an edit role
+
+The detail endpoint supports tabular query options for the linked locality list.
+
+## Frontend usage
+
+- `/museum/:id?` routes to the museum detail page.
+- Locality edit views use the museum lookup list when linking museums to a locality.
+- The Museum tab in locality details edits `now_mus` rows through the locality edit payload rather than by editing the museum record directly.
+
+## Validation notes
+
+Museum codes are treated as stable identifiers. Backend tests cover creation, update, empty-code validation, and duplicate-code checks that differ only by case.

documentation/entities/people.md

@@ -0,0 +1,54 @@
+# People
+
+People represent contributors, coordinators, contacts, and optionally application users. A person can exist without a login account.
+
+## Database model
+
+The main person record is `com_people`:
+
+- `initials` (primary key)
+- `first_name`
+- `surname`
+- `full_name`
+- `format`
+- `email`
+- `user_id`
+- `organization`
+- `country`
+- `password_set`
+- `used_morph`
+- `used_now`
+- `used_gene`
+
+If `user_id` is set, it links the person to a `com_users` row:
+
+- `user_id` (primary key)
+- `user_name`
+- `password`
+- `newpassword`
+- `last_login`
+- `now_user_group`
+- `mor_user_group`
+- `gen_user_group`
+
+Person initials are also used in coordinator, authorizer, contact, and membership relations, including project people, region coordinators, species coordinators, stratigraphy coordinators, and update-log coordinator/authorizer fields.
+
+## API endpoints
+
+- `GET /person/all`: list all people; admin-only
+- `GET /person/:id`: read person details; admin users can read any person and non-admin users can read only their own person record
+- `PUT /person`: update a person; admin users can update any person and non-admin users can update only their own person record
+
+Creating new people is not implemented through `PUT /person`; the route returns an error when `initials` is missing.
+
+## Frontend usage
+
+- `/person` shows the people table for admins.
+- `/person/:id?` shows person details when the signed-in user is authorized.
+- Person lookup data is reused by coordinator/contact selectors, such as project and region editing.
+
+## Permission notes
+
+The person routes intentionally do not use only the shared role middleware because self-service profile access is allowed. Route-level checks compare `req.user.initials` with the requested or edited person initials.
+
+Admin-only user-group edits are handled during person update when the payload includes a valid `user_id` and `now_user_group`.