# pedscoffee/physicianpromptengineering architecture

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

- Interactive diagram: https://gitdiagram.com/pedscoffee/physicianpromptengineering
- Repository: https://github.com/pedscoffee/physicianpromptengineering

## Overview

##### Project type and purpose
- This is a documentation‐centric static website built with a static site generator (Jekyll).
- Purpose: host and maintain an open‐source library of clinical AI prompts, courses, blog posts, data‐driven pages, and interactive browser-based tools.

##### File structure
- Top-level “source” directories:
- _posts, _course_modules, _prompts, .md pages (index.md, about.md, etc.) – these are your content/data nodes.
- _layouts, _includes – HTML template layers.
- _data – YAML data that can drive content or exercises.
- assets/css, assets/js, images – static assets and client-side scripts for interactive prototypes and styling.
- Configuration and build: Gemfile, _config.yml, CNAME, README.md – Jekyll config, dependencies, and meta.
- No dynamic backend: all pages are precompiled into HTML/CSS/JS.

##### README for additional insights
- Confirms Jekyll‐style static site, driving real-world prompt engineering resources.
- References interactive browser AI tools (client-side JS), analytics, forms (hosted externally), and contribution workflows via GitHub.

a. Main components
1. Content Repository (GitHub)
– Markdown content (_posts, .md pages)
– YAML data (_data)
– Prompt text files (_prompts)
2. Static Site Generator (Jekyll)
– Reads content + data + templates
– Applies layouts (_layouts) and includes (_includes)
– Outputs static HTML/CSS/JS
3. Assets & Client-Side Tools
– CSS (style.scss → style.css)
– JS modules (course-exercise.js, dropdown.js, browser AI prototypes)
4. Hosting/CD Pipeline
– CI (GitHub Actions or Netlify) runs `jekyll build` on push
– Deploy to GitHub Pages or Netlify CDN
5. External Services
– Google Analytics (snippet in _includes)
– Mailing list/forms (newsletter-onboarding, external CTA)
– GitHub Issues/Discussions for contributions

b. Relationships & Interactions
– Developer pushes markdown/YAML to GitHub → CI triggers Jekyll build → generates site artifacts → deploy → CDN serves site.
– Browser fetches HTML → loads CSS for styling & JS for interactive course modules.
– JS may call external APIs (if any) for in-browser AI demos (marked beta).
– Google Analytics snippet collects usage metrics.
– Users navigate, fill forms (e.g., newsletter), which post to external form service.

c. Architectural patterns and principles
– Static site architecture (content-as-code, no server-side runtime)
– MVC analogy: Data (YAML, Markdown) + Views (layouts, includes) + Controller (Jekyll engine)
– Modular design: separate course modules, prompts library, interactive prototypes.
– Progressive enhancement: HTML first, CSS styling, JS for added interactivity.

d. Key technologies/frameworks
– Ruby & Jekyll (static site generator)
– SCSS (style preprocessing)
– Vanilla JS for interactive components
– GitHub CI/CD (Actions/Pages) or Netlify
– External analytics and form services

##### Elements
- Developer push → CI/CD → Build Engine
- Build Engine → Static Site Output → CDN
- Browser requests → CDN → serves HTML/CSS/JS
- Blue for static components (content, SSG)
- Green for build/deploy pipeline
- Orange for client-side interactivity
- Gray for external services

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    Developer["Developer"]:::actor

    %% Content Repository
    subgraph "Content Repository" 
        direction TB
        MC["_posts"]:::static
        CMod["_course_modules"]:::static
        Pages[".md Pages"]:::static
        Prom["_prompts"]:::static
        Y1["_data/course_exercises.yml"]:::static
        Y2["_data/course_transcripts.yml"]:::static
        Y3["_data/diagnosis_cases.yml"]:::static
    end

    %% CI/CD Pipeline
    CICD["CI/CD Pipeline<br/>(GitHub Actions / Netlify)"]:::build

    %% Static Site Generator
    subgraph "Jekyll Build Engine" 
        direction TB
        Config["_config.yml"]:::build
        Gem["Gemfile"]:::build
        subgraph "Layouts"
            direction TB
            L1["_layouts/course.html"]:::build
            L2["_layouts/course_module.html"]:::build
            L3["_layouts/default.html"]:::build
            L4["_layouts/post.html"]:::build
        end
        subgraph "Includes"
            direction TB
            I1["_includes/head.html"]:::build
            I2["_includes/footer.html"]:::build
            I3["_includes/google-analytics.html"]:::external
            I4["_includes/newsletter-onboarding.html"]:::external
            I5["_includes/newsletter.html"]:::external
            I6["_includes/share-prompt-cta.html"]:::build
            I7["_includes/beta-notice.html"]:::build
        end
    end

    %% Static Output & Hosting
    Output["Static Site Output<br/>(HTML/CSS/JS)"]:::static
    CDN["CDN/Hosting<br/>(GitHub Pages / Netlify CDN)"]:::build

    %% User Browser and Assets
    Browser["User Browser"]:::client
    subgraph "Assets & Client-Side Tools"
        direction TB
        CSS["assets/css/style.scss"]:::client
        JS1["assets/js/course-exercise.js"]:::client
        JS2["assets/js/dropdown.js"]:::client
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GA["Google Analytics"]:::external
        NewsOnb["Newsletter Onboarding Form"]:::external
        News["Newsletter Form"]:::external
        AI["External AI Demo API (beta)"]:::external
    end

    %% Relationships
    Developer -->|"pushes content"| CICD
    CICD -->|"trigger build"| Config
    Config --> Gem
    Gem --> L1
    L1 --> I1
    I1 --> Output
    I2 --> Output
    I3 --> Output
    I4 --> Output
    I5 --> Output
    I6 --> Output
    I7 --> Output
    Output --> CDN
    CDN --> Browser
    Browser --> CSS
    Browser --> JS1
    Browser --> JS2
    Browser --> GA
    Browser --> NewsOnb
    Browser --> News
    JS1 -.->|"calls API"| AI

    %% Click Events
    click MC "https://github.com/pedscoffee/physicianpromptengineering/tree/main//_posts/"
    click CMod "https://github.com/pedscoffee/physicianpromptengineering/tree/main//_course_modules/"
    click Prom "https://github.com/pedscoffee/physicianpromptengineering/tree/main//_prompts/"
    click Y1 "https://github.com/pedscoffee/physicianpromptengineering/blob/main//_data/course_exercises.yml"
    click Y2 "https://github.com/pedscoffee/physicianpromptengineering/blob/main//_data/course_transcripts.yml"
    click Y3 "https://github.com/pedscoffee/physicianpromptengineering/blob/main//_data/diagnosis_cases.yml"
    click Config "https://github.com/pedscoffee/physicianpromptengineering/blob/main//_config.yml"
    click Gem "https://github.com/pedscoffee/physicianpromptengineering/tree/main/Gemfile"
    click L1 "https://github.com/pedscoffee/physicianpromptengineering/blob/main//_layouts/course.html"
    click L2 "https://github.com/pedscoffee/physicianpromptengineering/blob/main//_layouts/course_module.html"
    click L3 "https://github.com/pedscoffee/physicianpromptengineering/blob/main//_layouts/default.html"
    click L4 "https://github.com/pedscoffee/physicianpromptengineering/blob/main//_layouts/post.html"
    click I1 "https://github.com/pedscoffee/physicianpromptengineering/blob/main//_includes/head.html"
    click I2 "https://github.com/pedscoffee/physicianpromptengineering/blob/main//_includes/footer.html"
    click I3 "https://github.com/pedscoffee/physicianpromptengineering/blob/main//_includes/google-analytics.html"
    click I4 "https://github.com/pedscoffee/physicianpromptengineering/blob/main//_includes/newsletter-onboarding.html"
    click I5 "https://github.com/pedscoffee/physicianpromptengineering/blob/main//_includes/newsletter.html"
    click I6 "https://github.com/pedscoffee/physicianpromptengineering/blob/main//_includes/share-prompt-cta.html"
    click I7 "https://github.com/pedscoffee/physicianpromptengineering/blob/main//_includes/beta-notice.html"
    click CSS "https://github.com/pedscoffee/physicianpromptengineering/blob/main//assets/css/style.scss"
    click JS1 "https://github.com/pedscoffee/physicianpromptengineering/blob/main//assets/js/course-exercise.js"
    click JS2 "https://github.com/pedscoffee/physicianpromptengineering/blob/main//assets/js/dropdown.js"
    click CDN "https://github.com/pedscoffee/physicianpromptengineering/tree/main/CNAME"

    %% Styles
    classDef static fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef build fill:#90EE90,stroke:#333,stroke-width:1px
    classDef client fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef actor fill:#9370DB,stroke:#333,stroke-width:1px
```
