How cywhale/copkey works
Project Type and Purpose
• This is a hybrid project combining:
• A full-stack web application (“copkey”): a Preact front end talking to a Node.js back end (Express + GraphQL + REST) that serves taxonomic data from a MongoDB.
• A static documentation pipeline (R scripts + Bookdown) generating multiple HTML sites (copkey_book, genus, www, www_sp).
• Purpose: provide interactive identification keys for Calanoid copepods and host richly illustrated taxonomic reference books online.
File Structure Analysis
• Top-level folders:
• R/ and copkey_book/: R-based content-generation, Bookdown build artifacts under _book folders.
• script/: shell/PowerShell helpers to convert docx/images to markdown, etc.
• app/: Node.js back end (Express server, GraphQL schema/resolvers, Mongoose models, Redis cache plugin).
• client/: Preact front end (webpack/pnpm, components, styles, service worker).
• genus/, www/, www_sp/: static HTML outputs of other Bookdown or R Markdown sites.
• Key config files: package.json and pm2.sh (deployment) in app/, pnpm-lock.json in client/, .gitignore, .gitattributes, Git submodules.
Insights from README
• Describes the interactive web app and links to static book sites.
• Confirms dual nature: dynamic React-style UI for species key and static book pages for taxonomy.
Main Components and Their Interactions
a. Static Content Pipeline (Bookdown/R Scripts)
• R scripts (in R/) ingest Rmd/docx assets → produce HTML via bookdown → output under copkey_book/_book, www/_book, genus/_book.
• Deployment targets: GitHub Pages or static file host serving these directories as standalone websites.
b. Back End (app/)
• Express server (srvapp.js / index.js)
• API layer:
– REST endpoints (routes/apirest.js, routes/frontend.js, routes/spfig.js)
– GraphQL endpoint (routes/querygql.js + schema.js + resolvers.js)
• Data layer: Mongoose models (models/spkey_mongoose.js) connecting to MongoDB.
• Plugins: Redis cache (plugins/redis.js), in-memory cache (plugins/cache.js).
• Deployment: pm2.sh for process management.
c. Front End (client/)
• Preact single-page app in src/components, built via pnpm and webpack (preact.config.js).
• Service worker (sw.js) for offline caching.
• Interacts with back end over HTTP:
– GraphQL queries/mutations
– REST for images or figure downloads.
d. External Services
• MongoDB as primary data store.
• Redis for caching API responses.
• Static file host or CDN for serving built front end and static book sites.
Architectural Patterns and Principles
• Clear separation of concerns:
• Static documentation pipeline isolated from dynamic app.
• Front end (view) ↔ API layer (GraphQL/REST) ↔ Data layer (models + DB).
• Plugin architecture in back end for cross-cutting concerns (cache, redis).
• Content generation pipeline using declarative R Markdown and bookdown.
• CI/CD implied by git structure and pm2 deployment script.