# cywhale/copkey architecture

> Architecture diagram of the GitHub repository cywhale/copkey, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cywhale/copkey
- Repository: https://github.com/cywhale/copkey

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% R-based Static Pipeline
    subgraph "R Pipeline" 
        direction TB
        R_Scripts["R Scripts (R/)"]:::static
        Scripts["Helper Scripts (script/)"]:::static
        Bookdown["Bookdown Engine"]:::static
        R_Scripts -->|ingest Rmd/docx| Bookdown
        Scripts -->|prepare assets| Bookdown
    end

    %% Static Sites Outputs
    subgraph "Static Sites Outputs" 
        direction TB
        CopkeyBook["copkey_book/_book"]:::static
        GenusBook["genus/_book"]:::static
        WWWBook["www/_book"]:::static
        WWWSpBook["www_sp/_book"]:::static
        Bookdown --> CopkeyBook
        Bookdown --> GenusBook
        Bookdown --> WWWBook
        Bookdown --> WWWSpBook
    end

    %% Dynamic App Back End
    subgraph "Back End (app/)" 
        direction TB
        EB["Express Server\n(app/src/index.js, srvapp.js)"]:::backend
        PM2["Deployment Script\n(pm2.sh)"]:::backend
        EB --> PM2
        subgraph "API Layer" 
            direction TB
            REST["REST Endpoints\n(apirest.js, frontend.js, spfig.js)"]:::backend
            GQL["GraphQL Endpoint\n(querygql.js)"]:::backend
        end
        subgraph "GraphQL Schema & Resolvers"
            direction TB
            Schema["schema.js"]:::backend
            Resolvers["resolvers.js"]:::backend
            KeyStrx["keystrx.js"]:::backend
            KeyTree["keytree.js"]:::backend
            GQL --> Schema --> Resolvers
            Resolvers --> KeyStrx
            Resolvers --> KeyTree
        end
        subgraph "Data & Plugins"
            direction TB
            Model["Mongoose Model\n(spkey_mongoose.js)"]:::backend
            RedisPlugin["Redis Cache Plugin\n(redis.js)"]:::backend
            MemCache["In-memory Cache\n(cache.js)"]:::backend
            EB --> REST
            EB --> GQL
            REST --> Model
            GQL --> Model
            EB --> RedisPlugin
            EB --> MemCache
            Model --> RedisPlugin
        end
    end

    %% Front End
    subgraph "Front End (client/)" 
        direction TB
        SPA["Preact SPA\n(src/index.js)"]:::frontend
        Components["UI Components\n(src/components/)"]:::frontend
        Config["Webpack Config\n(preact.config.js)"]:::frontend
        SW["Service Worker\n(sw.js, sw_register.js)"]:::frontend
        SPA --> Components
        SPA --> Config
        SPA --> SW
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Browser["Browser"]:::external
        MongoDB["MongoDB"]:::external
        Redis["Redis"]:::external
        StaticHost["Static File Host/CDN"]:::external
    end

    %% Data Flows
    Browser -->|serves assets| SPA
    Browser -->|requests static site| StaticHost
    SPA -->|REST/GraphQL calls| EB
    EB -->|queries| MongoDB
    EB -->|caches responses| Redis
    CopkeyBook -->|host site| StaticHost
    GenusBook -->|host site| StaticHost
    WWWBook -->|host site| StaticHost
    WWWSpBook -->|host site| StaticHost

    %% Click Events
    click R_Scripts "https://github.com/cywhale/copkey/tree/main/R/"
    click Scripts "https://github.com/cywhale/copkey/tree/main/script/"
    click CopkeyBook "https://github.com/cywhale/copkey/tree/main/copkey_book/_book/"
    click GenusBook "https://github.com/cywhale/copkey/tree/main/genus/_book/"
    click WWWBook "https://github.com/cywhale/copkey/tree/main/www/_book/"
    click WWWSpBook "https://github.com/cywhale/copkey/tree/main/www_sp/_book/"
    click EB "https://github.com/cywhale/copkey/blob/main/app/src/index.js"
    click PM2 "https://github.com/cywhale/copkey/blob/main/app/pm2.sh"
    click REST "https://github.com/cywhale/copkey/blob/main/app/src/routes/apirest.js"
    click REST "https://github.com/cywhale/copkey/blob/main/app/src/routes/frontend.js"
    click REST "https://github.com/cywhale/copkey/blob/main/app/src/routes/spfig.js"
    click GQL "https://github.com/cywhale/copkey/blob/main/app/src/routes/querygql.js"
    click Schema "https://github.com/cywhale/copkey/blob/main/app/src/graphql/schema.js"
    click Resolvers "https://github.com/cywhale/copkey/blob/main/app/src/graphql/resolvers.js"
    click KeyStrx "https://github.com/cywhale/copkey/blob/main/app/src/graphql/keystrx.js"
    click KeyTree "https://github.com/cywhale/copkey/blob/main/app/src/graphql/keytree.js"
    click Model "https://github.com/cywhale/copkey/blob/main/app/src/models/spkey_mongoose.js"
    click RedisPlugin "https://github.com/cywhale/copkey/blob/main/app/src/plugins/redis.js"
    click MemCache "https://github.com/cywhale/copkey/blob/main/app/src/plugins/cache.js"
    click SPA "https://github.com/cywhale/copkey/blob/main/client/src/index.js"
    click Components "https://github.com/cywhale/copkey/tree/main/client/src/components/"
    click Config "https://github.com/cywhale/copkey/blob/main/client/config/preact.config.js"
    click SW "https://github.com/cywhale/copkey/blob/main/client/src/sw.js"
    click SW "https://github.com/cywhale/copkey/blob/main/client/src/sw_register.js"

    %% Styles
    classDef static fill:#D0E6F8,stroke:#4DA1E4,color:#03396C
    classDef backend fill:#DFF0D8,stroke:#3C763D,color:#336633
    classDef frontend fill:#FDEBD0,stroke:#E67E22,color:#A04000
    classDef external fill:#EEEEEE,stroke:#AAAAAA,color:#555555
```
