Skip to content

architecture.md

Latest commit

 

History

History
98 lines (74 loc) · 4.53 KB

architecture.md

File metadata and controls

98 lines (74 loc) · 4.53 KB
Raw

Architecture

High-level map of Cimo for engineers and agents.

Canonical product should: docs/prd/README.md
Premium should: pro__premium_only/docs/prd/README.md
Glossary: CONTEXT.md · ADRs: docs/adr/
Subsystem contracts: colocated CONTRACT.md
How-it-works: colocated maps (implementation only - must not invent product law)

Product surface

Cimo is a browser-first media optimizer for WordPress:

  • Primary runtime: capture-phase upload interception → Converter → optimized File → native WP upload
  • Settings: React admin page writing cimo_options
  • PHP: enqueue, REST, metadata attach, stats, caps - not the primary encode engine

Free = instant image WebP on upload. Premium = same spine + formats, smart optimize, bulk rewrite, forms, LQIP, stealth, Freemius lite.

System diagram

 User drop / file input
         │
         ▼
 ┌───────────────────────────┐
 │ Upload interception       │  drop-zone / select-files (capture)
 │ media-manager             │
 └─────────────┬─────────────┘
               │ getFileConverter(file)
               ▼
 ┌───────────────────────────┐     applyFilters (premium)
 │ Conversion engine         │◄──── video/audio/svg/heic/smart
 │ shared/converters         │
 └─────────────┬─────────────┘
               │ { file, metadata }
               ▼
 ┌───────────────────────────┐
 │ saveMetadata REST         │  queue by filename
 └─────────────┬─────────────┘
               │ synthetic event + __cimo_converted
               ▼
 ┌───────────────────────────┐
 │ WordPress / builder upload│
 └─────────────┬─────────────┘
               │ add_attachment match
               ▼
 ┌───────────────────────────┐
 │ cimo meta + stats         │──► sidebar / metabox / settings
 └───────────────────────────┘

 Premium bulk (separate surface):
 settings BulkOptimizer → convert sizes in browser → upload/restore REST → backups + stats

Bootstrap

  1. cimo.php defines CIMO_BUILD (free | premium) and loads free PHP classes.
  2. If premium and pro__premium_only/index.php exists, require it.
  3. Premium always initializes Freemius lite; feature classes load when plan is premium or agency.

Build scripts flip CIMO_BUILD and webpack entries (admin/index, admin/admin-page; premium adds *-premium and LQIP).

Major subsystems

Subsystem Code Contract / PRD
Upload interception src/admin/js/media-manager/ CONTRACT · PRD
Conversion engine src/shared/converters/ CONTRACT · PRD
Attachment intelligence src/admin/class-metadata.php, class-stats.php, class-meta-box.php, sidebar-info CONTRACT · PRD
Bulk (shared) src/admin/class-bulk-library.php, bulk-optimizer upsell PRD
Bulk (premium) pro__premium_only/.../class-bulk-optimization.php, bulk-optimizer UI Premium PRD
Settings shell src/admin/js/page/ CONTRACT · PRD
Freemius lite pro__premium_only/freemius.php, FSLite Premium PRD

Freemium seams (summary)

Premium extends free through filters/actions rather than forking the spine. See free-vs-premium for the matrix and the conversion/upload/settings PRDs for named hooks.

Doc precedence

When code, how-it-works, and PRD/contract disagree: PRD/contract win. Open a GitHub issue for deepen/refactor opportunities that improve locality without changing product promises.