# Systems Documentation

**Last Updated:** 2026-01-10

Complete documentation for all systems, components, APIs, and integrations used across the Ordio website.

## Overview

This directory contains comprehensive documentation for:

- **Forms System** - All form endpoints, configurations, and mappings
- **Shared Components** - Reusable JavaScript and PHP components
- **APIs** - HubSpot API integration and endpoints
- **Lead Capture** - Two-step progressive lead capture system

## Quick Navigation

### Quick Start

- **[Quick Reference Card](QUICK_REFERENCE_CARD.md)** - One-page quick reference for common tasks
- **[Developer Quick Reference](DEVELOPER_QUICK_REFERENCE.md)** - Comprehensive quick reference guide

### Forms & Form Submissions

- **[Form-to-Page Mapping](forms/FORM_TO_PAGE_MAPPING.md)** - Complete mapping of forms to pages/tools/templates
- **[Form Configuration Reference](forms/FORM_CONFIGURATION_REFERENCE.md)** - Form GUIDs, field mappings, and requirements
- **[Data Flow Diagrams](forms/DATA_FLOW_DIAGRAMS.md)** - Visual data flow representations

### Shared Components

- **[Component Overview](shared-components/README.md)** - Overview of all shared components
- **[Email Modal Component](shared-components/EMAIL_MODAL_COMPONENT.md)** - Email collection modal for tools
- **[Email Modal Utils](shared-components/EMAIL_MODAL_UTILS.md)** - Email validation and storage utilities
- **[UTM Tracking System](shared-components/UTM_TRACKING_SYSTEM.md)** - UTM parameter tracking
- **[GTM Form Tracking](shared-components/GTM_FORM_TRACKING.md)** - Google Tag Manager form tracking
- **[Lead Capture Component](shared-components/LEAD_CAPTURE_COMPONENT.md)** - Two-step lead capture popup
- **[Component Usage Guide](shared-components/COMPONENT_USAGE_GUIDE.md)** - Practical integration guide

### APIs

- **[HubSpot API Reference](apis/HUBSPOT_API_REFERENCE.md)** - Complete reference for all 9 HubSpot API endpoints

### Lead Capture System

- **[Lead Capture System](systems/lead-capture/README.md)** - Complete lead capture system documentation
- **[Architecture](systems/lead-capture/ARCHITECTURE.md)** - System architecture
- **[Integration Guide](systems/lead-capture/INTEGRATION_GUIDE.md)** - Integration patterns

## Documentation Structure

```
docs/systems/
├── README.md (this file)
├── forms/
│   ├── FORM_TO_PAGE_MAPPING.md
│   ├── FORM_CONFIGURATION_REFERENCE.md
│   └── DATA_FLOW_DIAGRAMS.md
├── shared-components/
│   ├── README.md
│   ├── EMAIL_MODAL_COMPONENT.md
│   ├── EMAIL_MODAL_UTILS.md
│   ├── UTM_TRACKING_SYSTEM.md
│   ├── GTM_FORM_TRACKING.md
│   ├── LEAD_CAPTURE_COMPONENT.md
│   └── COMPONENT_USAGE_GUIDE.md
└── apis/
    └── HUBSPOT_API_REFERENCE.md
```

## Related Documentation

### Guides

- **[HubSpot Integration Guide](guides/HUBSPOT_INTEGRATION_GUIDE.md)** - Complete HubSpot integration guide
- **[Form Tracking Developer Guide](../forms/FORM_TRACKING_DEVELOPER_GUIDE.md)** - GTM form tracking guide

### Forms Documentation

- **[Form Audit Report](../forms/form-audit-report.md)** - Form audit findings
- **[Form IDs Reference](../forms/form-ids-reference.md)** - Form ID quick reference
- **[HubSpot Form Field Configuration](guides/HUBSPOT_FORM_FIELD_CONFIGURATION.md)** - HubSpot form configuration

### Lead Capture Documentation

- **[Lead Capture System](lead-capture/README.md)** - Lead capture system overview
- **[Architecture](lead-capture/ARCHITECTURE.md)** - System architecture
- **[Integration Guide](lead-capture/INTEGRATION_GUIDE.md)** - Integration patterns

## Common Tasks

### Adding a New Tool/Calculator

1. Review [Component Usage Guide](shared-components/COMPONENT_USAGE_GUIDE.md) - Pattern 1
2. Add email modal integration
3. Update [Form-to-Page Mapping](forms/FORM_TO_PAGE_MAPPING.md)
4. Test form submission

### Adding a New Template Download

1. Review [Component Usage Guide](shared-components/COMPONENT_USAGE_GUIDE.md) - Pattern 2
2. Add form submission handler
3. Update [Form-to-Page Mapping](forms/FORM_TO_PAGE_MAPPING.md)
4. Test form submission

### Adding Lead Capture to a Page

1. Review [Component Usage Guide](shared-components/COMPONENT_USAGE_GUIDE.md) - Pattern 3
2. Include lead capture component
3. Test triggers and form submission

### Creating a New API Endpoint

1. Review [HubSpot API Reference](apis/HUBSPOT_API_REFERENCE.md)
2. Follow Forms API v3 patterns
3. Add to [Form Configuration Reference](forms/FORM_CONFIGURATION_REFERENCE.md)
4. Update [Form-to-Page Mapping](forms/FORM_TO_PAGE_MAPPING.md)

## Documentation Standards

All documentation follows these standards:

- **Last Updated:** Date in YYYY-MM-DD format
- **File Naming:** UPPERCASE_WITH_UNDERSCORES.md
- **Structure:** Overview → Details → Examples → Related Docs
- **Code Examples:** Complete, runnable examples
- **Cross-References:** Links to related documentation

## Contributing

When updating documentation:

1. Update "Last Updated" date
2. Add cross-references to related docs
3. Include code examples
4. Update this README if adding new sections
5. Follow existing documentation structure