Docs: add Project/Region/Occurrence entity docs

documentation/entities/occurrence.md

@@ -0,0 +1,26 @@
+# Occurrences
+
+An “occurrence” is a *composite* record: it represents the relationship between a **Locality** (`lid`) and a **Species** (`species_id`) and the editable occurrence-specific fields associated with that pair.
+
+## Composite key
+
+Occurrences are uniquely identified by:
+
+- `lid` (locality id)
+- `species_id` (species id)
+
+## API endpoints
+
+- `GET /occurrence/:lid/:speciesId` (authenticated): read occurrence details
+- `PUT /occurrence/:lid/:speciesId` (edit roles): update occurrence-specific fields for the (lid, species_id) pair
+
+## Editable fields (high level)
+
+The editable payload is a partial object (`EditableOccurrenceData`) that includes fields such as:
+
+- counts / measurements (for example `nis`, `pct`, `quad`, `mni`, `body_mass`)
+- qualitative strings (for example `qua`, `id_status`, `orig_entry`, `source_name`)
+- wear / isotopes / derived fields (for example `mesowear`, `microwear`, `dc13_*`, `do18_*`, `mw_*`)
+
+Non-editable fields in the detail response include locality and taxonomy context (for example `loc_name`, `country`, `genus_name`, `species_name`) so the occurrence page can be rendered without extra fetches.
+

documentation/entities/project.md

@@ -0,0 +1,28 @@
+# Projects
+
+Projects are used to group data entries under a shared “project” (for example, a locality can be linked to one or more projects).
+
+## Database model
+
+The main project record is `now_proj`:
+
+- `pid` (primary key)
+- `proj_code` (short code)
+- `proj_name` (display name)
+- `proj_status`
+- `contact` (links to a person by `com_people.initials`)
+
+Relations that are commonly included in detail payloads:
+
+- `now_proj_people`: coordinators / people attached to the project (`now_proj_people.initials` → `com_people.initials`)
+
+Localities are linked to projects via `now_plr` (composite key: `lid` + `pid`).
+
+## API endpoints
+
+- `GET /project/all` (authenticated): list projects visible to the current user
+- `GET /project/:id` (admin): project details
+- `POST /projects` (admin): create a project
+- `PUT /projects/:id` (admin): update a project
+- `DELETE /project/:id` (admin): delete a project
+

documentation/entities/region.md

@@ -0,0 +1,28 @@
+# Regions
+
+Regions represent a named geographic region that can be associated with:
+
+- one or more countries (`now_reg_coord_country`)
+- one or more coordinators / people (`now_reg_coord_people` → `com_people`)
+
+## Database model
+
+The main region record is `now_reg_coord`:
+
+- `reg_coord_id` (primary key)
+- `region` (name)
+
+Relations:
+
+- `now_reg_coord_country` rows (composite key: `reg_coord_id` + `country`)
+- `now_reg_coord_people` rows (composite key: `reg_coord_id` + `initials`)
+
+## API endpoints
+
+All region endpoints are admin-only:
+
+- `GET /region/all`
+- `GET /region/:id`
+- `PUT /region` (create/update; returns `{ reg_coord_id }`)
+- `DELETE /region/:id`
+

documentation/entities/species.md

@@ -13,3 +13,12 @@ A species has the following required fields in the database:
 - `unique_identifier`
 
 All of these are also required when editing or creating a new species (with the exception of `species_id`). The `class_name` is set to "Mammalia" by default and cannot be edited.
+
+## Synonyms
+
+Species synonyms are stored in `com_taxa_synonym` and are shown in some list views to help users find the accepted taxonomy using alternative names.
+
+The UI often needs only the “list synonym” display fields:
+
+- `syn_genus_name`
+- `syn_species_name`