peptide-starter-theme/ARCHITECTURE.md

Peptide Starter Theme - Architecture

Overview

Peptide Starter (peptide-starter) is a premium, accessible WordPress theme for peptiderepo.com — a scientific peptide reference database. The theme is a classic (non-block) WordPress theme that assembles a modern, responsive frontend by combining a monolithic CSS architecture with vanilla JavaScript. It integrates seamlessly with five companion plugins (Peptide Search AI, Peptide News, PRAutoBlogger, Peptide Tools, Peptide Tracker, Peptide Community) via shortcodes, coordinates dark mode across the ecosystem via CSS custom properties and the DOM data-theme attribute, and provides customizable hero, navigation, authentication, and footer sections.

Directory Structure

peptide-starter/
├── style.css                    # All theme CSS. Architecture: reset → tokens → typography →
│                                 # globals → components → regions → pages → animations →
│                                 # a11y → dark mode → responsive → new feature sections
│
├── functions.php                # Theme setup entry point (~206 lines)
│                                 # - Constants, feature module loading
│                                 # - Theme support registration
│                                 # - Script/style enqueueing (incl conditional)
│                                 # - Widget areas, newsletter handler, dark mode inline script
│
├── inc/
│   ├── helpers.php              # Nav walker, custom logo, hero/footer getters, pagination
│   ├── customizer.php           # Customizer sections, settings, sanitize callbacks
│   ├── auth-handlers.php        # AJAX login + registration handlers
│   ├── contact-handler.php      # AJAX contact form handler (settings panel)
│   ├── page-setup.php           # Auto-create pages on theme activation
│   └── newsletter-admin.php     # Admin page to view/export subscriber emails
│
├── header.php                   # Global header (~190 lines)
│                                 # - Site logo, primary navigation with dropdowns
│                                 # - Sign In / User menu (state-aware)
│                                 # - Settings icon, language placeholder
│                                 # - Search, dark mode toggle, cart, mobile menu
│                                 # - Search overlay, fallback nav
│
├── footer.php                   # Global footer (~100 lines)
│                                 # - Newsletter signup (front page via template part)
│                                 # - 4-column widget grid with updated defaults
│                                 # - Copyright, disclaimer, language links
│                                 # - Settings panel include
│
├── front-page.php               # Home page template (~100 lines)
│                                 # - Hero section (title, subtitle, search, CTAs)
│                                 # - Research Modules grid (6 cards)
│                                 # - [prautoblogger_posts] shortcode
│                                 # - [peptide_news] shortcode
│
├── page-calculator.php          # Calculator page template → [peptide_tools_calculator]
├── page-protocol-builder.php    # Protocol Builder template → [peptide_tools_protocol_builder]
├── page-tracker.php             # Tracker template → [peptide_tracker]
├── page-subject-log.php         # Subject Log template → [peptide_tracker_subject_log]
├── page-documentation.php       # Documentation/SOP page — two-column layout with ToC sidebar
├── page-directory.php           # Peptide Directory template → [peptide_directory]
├── page-science-feed.php        # Science Feed template → [peptide_news] + newsletter
├── page-profile.php             # User Profile template → [peptide_community_profile]
├── page-auth.php                # Sign In / Register — branded auth forms with AJAX
│
├── page.php                     # Generic page template
├── index.php                    # Fallback template
├── single-peptide.php           # Peptide detail page (CPT)
├── archive-peptide.php          # Peptide archive (CPT grid)
├── 404.php                      # 404 error page
├── searchform.php               # Search form template
│
├── template-parts/
│   ├── content.php              # Default post/page loop item
│   ├── content-peptide.php      # Peptide CPT card template
│   ├── content-none.php         # Empty state template
│   ├── module-cards.php         # Research Modules 6-card grid (front page)
│   ├── newsletter-signup.php    # Reusable newsletter signup section
│   └── settings-panel.php       # Slide-out support/contact panel
│
├── assets/js/
│   ├── navigation.js            # Mobile menu toggle (85 lines)
│   ├── theme.js                 # Dark mode + search overlay + utilities (210 lines)
│   ├── documentation.js         # ToC generation + scroll spy for docs page (145 lines)
│   ├── auth.js                  # Auth form toggle, validation, AJAX (192 lines)
│   └── settings-panel.js        # Settings panel open/close + contact form (163 lines)
│
├── languages/                   # Translation files (.pot, .po, .mo)
├── tests/                       # PHPUnit tests
├── .phpcs.xml.dist              # PHPCS config
├── phpunit.xml                  # PHPUnit config
├── composer.json                # Dev dependencies
├── README.md                    # User-facing docs
├── CLAUDE.md                    # Developer context
├── CHANGELOG.md                 # Version history
└── screenshot.png               # Theme preview image

Navigation Structure

Home | Tools ▾ | My Data ▾ | Resources ▾ | [Sign In / Username ▾] ⚙ 🌐 🔍 🌙

Tools dropdown:
  ├── Calculator → /calculator
  ├── Protocol Builder → /protocol-builder
  └── Tracker → /tracker

My Data dropdown:
  ├── Peptides → /peptides
  └── Subject Log → /subject-log

Resources dropdown:
  ├── Documentation → /documentation
  └── Science Feed → /news

User menu (logged in):
  ├── My Profile → /profile
  ├── Tracker → /tracker
  ├── Subject Log → /subject-log
  └── Sign Out

Page Template Map

Page Title	Slug	Template File	Plugin Shortcode
Calculator	calculator	page-calculator.php	[peptide_tools_calculator]
Protocol Builder	protocol-builder	page-protocol-builder.php	[peptide_tools_protocol_builder]
Tracker	tracker	page-tracker.php	[peptide_tracker]
Subject Log	subject-log	page-subject-log.php	[peptide_tracker_subject_log]
Documentation	documentation	page-documentation.php	(WordPress content + JS ToC)
Peptide Directory	peptides	page-directory.php	[peptide_directory]
Science Feed	news	page-science-feed.php	[peptide_news]
Profile	profile	page-profile.php	[peptide_community_profile]
Sign In	auth	page-auth.php	(Custom auth forms)

Pages are auto-created on theme activation via inc/page-setup.php.

Data Flow & Architecture Diagrams

Front Page Assembly

front-page.php
    ├─→ Hero Section (title, subtitle, search, CTAs)
    │   └─→ [peptide_search] shortcode (Peptide Search AI plugin)
    │
    ├─→ Research Modules Grid (template-parts/module-cards.php)
    │   └─→ 6 cards linking to tool/section pages
    │       └─→ Checks shortcode_exists() for graceful degradation
    │
    ├─→ [prautoblogger_posts] shortcode (PRAutoBlogger plugin)
    │
    └─→ [peptide_news] shortcode (Peptide News plugin)

Authentication Flow

page-auth.php
    ├─→ Sign In form → auth.js AJAX → inc/auth-handlers.php
    │   └─→ wp_signon() → redirect to original page
    │
    └─→ Register form → auth.js AJAX → inc/auth-handlers.php
        └─→ wp_create_user() → auto-login → redirect to /profile

Dark Mode Coordination

functions.php (wp_head inline script)
    └─→ Sets html[data-theme] from localStorage → system pref → customizer default
        ├─→ style.css reads data-theme for color overrides
        └─→ theme.js dispatches 'themechange' event to plugins

External Integrations

Plugin Integrations (via Shortcodes)

1. Peptide Search AI ([peptide_search]) — Hero + search overlay. Namespace: .psa-*
2. Peptide News ([peptide_news]) — Front page + science feed. Namespace: .pn-*
3. PRAutoBlogger ([prautoblogger_posts]) — Front page articles. Namespace: .prab-*
4. Peptide Tools ([peptide_tools_calculator], [peptide_tools_protocol_builder]) — Tool pages
5. Peptide Tracker ([peptide_tracker], [peptide_tracker_subject_log]) — Tracker pages
6. Peptide Community ([peptide_community_profile], [peptide_directory]) — Profile + directory

All plugins checked with shortcode_exists() for graceful degradation.

Key Architectural Decisions

1. Classic Theme (Not FSE) — Stability, control, plugin compatibility
2. Monolithic CSS — No build step, CSS custom properties for abstraction
3. Vanilla JavaScript — No bundler, direct browser ES6+, node --check validation
4. Shortcode Integration — Decouples plugins from theme via shortcode_exists()
5. CSS Custom Properties for Dark Mode — Single source of truth for colors
6. No !important Policy — Explicit specificity over cascade tricks
7. Inline Dark Mode Script — Prevents flash of wrong theme on load
8. Split functions.php into inc/ — Keeps all files under 300 lines

Security

• CSRF nonces on all forms (auth, newsletter, contact)
• All input sanitized at boundary (sanitize_text_field, sanitize_email, sanitize_textarea_field)
• All output escaped (esc_html, esc_attr, esc_url, wp_kses_post)
• Login redirect validated with wp_validate_redirect() to prevent open redirects
• Auth form uses AJAX to avoid exposing credentials in URL
• Contact form topics restricted to allowlist

Version

Current: v1.5.0

When releasing a new version, update style.css header (line 7) and PEPTIDE_STARTER_VERSION in functions.php.