refactor: Split monolithic sysndd_plumber.R into smaller endpoint files

[berntpopp]

Summary

Our current sysndd_plumber.R script has grown large and unwieldy, mixing endpoint definitions for entities, reviews, re-reviews, publications, and more into a single file. This issue proposes refactoring the code to maintain each logical group of endpoints in its own file under a dedicated endpoints/ folder. The goal is better readability, maintainability, and testability of the API codebase.

Why This Matters

1. Maintainability: Smaller, domain-focused endpoint files make it easier to locate relevant code.
2. Collaboration: Team members can edit endpoint files without merging conflicts in the monolith.
3. Testability: Each endpoint set can be more easily unit tested, loaded, or debugged independently.
4. Clarity: Reduces confusion by separating business logic from the overarching API router code.

Proposed Implementation Plan

1. Create endpoints/ Folder

   • Under api/, create a new endpoints folder (i.e., api/endpoints/).

2. Identify Endpoint Sections in sysndd_plumber.R

   • Look for the major headings in the file, e.g.
     • ## Entity endpoints
     • ## Review endpoints
     • ## Re-review endpoints
     • ## Publication endpoints
     • ... and so forth.

3. Extract Endpoint Blocks into New Files

   • For each heading, create a corresponding file in endpoints/. Example:
     • api/endpoints/entity_endpoints.R
     • api/endpoints/review_endpoints.R
     • api/endpoints/re_review_endpoints.R
     • and so on.
   • Copy the relevant endpoints (the #* @get, #* @post definitions and their corresponding code) into the new file.
   • Remove the original code from sysndd_plumber.R once it’s in the new file.

4. Source Endpoint Files in sysndd_plumber.R

   • In the now-simplified sysndd_plumber.R, after loading libraries and config, source() each of the new endpoint files, e.g.:

     source("endpoints/entity_endpoints.R", local = TRUE)
     source("endpoints/review_endpoints.R", local = TRUE)
     ...

   • Ensure you still define the global #* @plumber function or any required hooks/filters in sysndd_plumber.R.

5. Ensure Helpers Remain in functions/

   • All shared logic remains in api/functions/*.R.
   • If new helper logic emerges while refactoring, create or expand the relevant file in functions/.

6. Validate and Test

   • Spin up the API using the existing mechanism (start_sysndd_api.R) or docker-compose as normal.
   • Verify that all endpoints remain functional by calling their routes.
   • Confirm that logs, authentication filters, or other shared behaviors (like CORS filter) still work.

7. Commit Messages / Branching

   • Use Conventional Commits style commits, e.g.:
     • refactor: split sysndd_plumber.R into endpoint-based files
     • chore: move entity endpoints to entity_endpoints.R
   • The main final commit might be refactor: finalize endpoint folder structure.

Tasks Checklist

• Create endpoints/ directory in api/.
• Extract each block from sysndd_plumber.R into its own file under endpoints/.
• Remove the extracted code from sysndd_plumber.R.
• In sysndd_plumber.R, source() the new endpoints/*.R files in a logical order.
• Verify that all hooks/filters in sysndd_plumber.R apply to the newly sourced endpoints.
• Test each endpoint route to ensure no breakage occurred.
• Commit with refactor: or chore: following Conventional Commits style.

---

References

• [Plumber documentation](https://www.rplumber.io/), for organizing endpoints in multiple files.
• [Conventional Commits](https://www.conventionalcommits.org/) style guide for commit messages.

---

Additional Notes

• Keep an eye out for duplicated code or references that might have existed in the monolith.
• Ensure environment variables and config remain available to each endpoint file (they are typically loaded once in sysndd_plumber.R, so no changes should be needed).