YPYM Company - Complete Architecture Documentation

🏗️ System Architecture Overview

This document provides a comprehensive guide to the YPYM Company platform architecture, covering the frontend layer, backend services, and web infrastructure.

Folder Structure Project

C:\Users\rochm\Documents\ypym-sandbox\ypym-company>

Architecture Diagram

🎨 Frontend Architecture

Technology Stack

Component	Technology	Version	Purpose
Framework	Astro	4.15.0	Static site generation & fast page loads
Styling	Tailwind CSS	3.4.0	Utility-first CSS framework
Language	TypeScript	5.5.0	Type-safe JavaScript development
Build Tool	TypeScript Checker	@astrojs/check 0.9.0	Pre-build type validation
Sitemap	@astrojs/sitemap	3.7.0	SEO-friendly sitemap generation
Node.js	Any LTS version	Recommended 18+	Runtime environment

Directory Structure

frontend/
├── astro.config.mjs              # Main Astro configuration
├── tailwind.config.mjs           # Tailwind design tokens
├── tsconfig.json                 # TypeScript configuration
├── package.json                  # Dependencies & scripts
│
├── src/
│   ├── env.d.ts                  # Environment type definitions
│   │
│   ├── components/               # 🧩 Reusable Components
│   │   ├── ui/                   # Basic UI components
│   │   │   ├── Button.astro      # CTA and action buttons
│   │   │   ├── Card.astro        # Card layout wrapper
│   │   │   ├── Hero.astro        # Hero section template
│   │   │   ├── forms/            # Form components
│   │   │   ├── interactive/      # Client-side interactive components
│   │   │   └── sections/         # Pre-built page sections
│   │   │
│   │   ├── seo/                  # 🔍 SEO Components
│   │   │   ├── Meta.astro        # Meta tags & head management
│   │   │   └── JsonLd.astro      # Structured data (JSON-LD)
│   │   │
│   │   ├── layout/               # Layout Wrappers
│   │   │   ├── Header.astro      # Navigation header
│   │   │   └── Footer.astro      # Footer section
│   │   │
│   │   └── ypym/                 # 🏢 Custom YPYM Components
│   │       ├── Badge.astro
│   │       ├── Button.astro
│   │       ├── Card.astro
│   │       ├── Hero3DChart.astro
│   │       ├── Hero3DSlider.astro
│   │       ├── HeroFunnel.astro
│   │       ├── HeroPuzzle.astro
│   │       ├── MatrixChart.astro
│   │       ├── PricingBlocks.astro
│   │       └── [30+ custom components]
│   │
│   ├── layouts/                  # 📐 Page Layouts
│   │   ├── BaseLayout.astro      # Default layout with SEO
│   │   ├── ArticleLayout.astro   # Blog article layout
│   │   ├── CaseStudyLayout.astro # Case study template
│   │   ├── ServiceLayout.astro   # Service details layout
│   │   └── GoogleLayout.astro    # Google-specific layout
│   │
│   ├── lib/                      # 🔧 Utilities & Services
│   │   ├── ghost.ts              # Ghost CMS API client
│   │   ├── seo.ts                # SEO helper functions
│   │   └── press-data.ts         # Press/media data
│   │
│   ├── pages/                    # 📄 Page Routes
│   │   ├── index.astro           # Homepage
│   │   ├── company.astro         # Company overview
│   │   ├── dev.astro             # Dev solutions page
│   │   ├── venture-studio.astro  # Venture studio page
│   │   │
│   │   ├── article/              # Blog articles
│   │   │   ├── [slug].astro      # Dynamic article page
│   │   │   ├── index.astro       # Articles index
│   │   │   └── tag/              # Tag-based filtering
│   │   │
│   │   ├── case-study/           # Case studies
│   │   │   ├── [slug].astro
│   │   │   └── index.astro
│   │   │
│   │   └── dev/                  # Development services
│   │       ├── enterprise-foundation.astro
│   │       ├── high-performance-frontend.astro
│   │       ├── intelligence-automation.astro
│   │       └── master-dev.astro
│   │
│   ├── scripts/                  # 🔨 Build Scripts
│   │   └── generate-sitemap.mjs  # Sitemap generator
│   │
│   ├── styles/                   # 🎨 Global Styles
│   │   └── global.css            # Global CSS & utilities
│   │
│   └── assets/                   # 📦 Static Assets
│       ├── images/
│       ├── icons/
│       └── fonts/
│
└── public/                       # 📁 Public static files
    └── robots.txt                # SEO robots directive

Build Process

Key Frontend Features

1. Image Optimization Engine

Service: Astro Sharp Integration
Formats: WebP, PNG, JPEG
Remote Domains:
- ghost.ypym.app (Production Ghost CMS)
- localhost:2368 (Development Ghost CMS)
- images.unsplash.com (Stock images)
Optimization: Automatic srcset generation, lazy loading
Input Limit: 192 MP (no pixel limit)

2. TypeScript Configuration

// tsconfig.json configuration
{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "strict": true,
    "target": "ES2020",
    "lib": ["ES2020"]
  }
}

3. Tailwind CSS Design System

Color Palette: Anthropic-inspired (sand, beige, accents)
Sand Colors: 50-900 scale
Accent Colors: Orange (#d97757), Black, White
Responsive: Mobile-first design
Customizations: Extended theme variables

4. Site Configuration

// Production site: https://ypym.app
// Development: http://localhost:4321

// Integrations:
- @astrojs/tailwind    // CSS framework
- @astrojs/sitemap     // XML sitemap generation
- astro/assets/services/sharp  // Image optimization

Development Commands

# Start development server (port 4321)
npm run dev
# or
npm start

# Production build with type checking
npm run build
# Process: Type check → Build → Generate sitemap

# Preview production build locally
npm run preview

# Run Astro CLI commands
npm run astro -- [command]

👻 Backend Architecture

Ghost CMS Overview

Ghost is a modern, open-source headless CMS designed for content management with API-first architecture.

Feature	Details
Version	5-alpine (lightweight Docker image)
Port	2368
Container Name	`tessera-ghost`
Mode	Headless (API-only, no default frontend)
Database	MySQL 8.0
Environment	Docker container (production-ready)

Ghost Architecture Diagram

Ghost API Endpoints

Content API (Public)

Used by Astro frontend for reading published content:

GET /ghost/api/v3/content/posts/
  ?key=CONTENT_API_KEY
  &limit=15
  &include=authors,tags
  &filter=status:published

GET /ghost/api/v3/content/authors/
  ?key=CONTENT_API_KEY

GET /ghost/api/v3/content/tags/
  ?key=CONTENT_API_KEY

GET /ghost/api/v3/content/pages/
  ?key=CONTENT_API_KEY
  &filter=status:published

Admin API (Authenticated)

Available at http://localhost:2368/ghost/api/admin/ for authenticated requests.

Ghost Environment Configuration

# Critical Environment Variables
URL=http://localhost:2368              # Ghost public URL
NODE_ENV=production                    # Running in production mode
DATABASE__CLIENT=mysql                 # MySQL database driver
DATABASE__CONNECTION__HOST=mysql       # Docker network hostname
DATABASE__CONNECTION__PORT=3306        # MySQL port
DATABASE__CONNECTION__USER=ghost       # Database user
DATABASE__CONNECTION__PASSWORD=***     # From MYSQL_PASSWORD env var
DATABASE__CONNECTION__DATABASE=ghost   # Database name

Ghost Docker Configuration

services:
  ghost:
    image: ghost:5-alpine
    container_name: tessera-ghost
    restart: always
    ports:
      - "2368:2368"
    environment:
      # Configuration as above
    volumes:
      - ghost_content:/var/lib/ghost/content    # Persistent content
    depends_on:
      mysql:
        condition: service_healthy               # Wait for MySQL health check
    networks:
      - tessera-network                         # Docker internal network

Ghost Frontend Integration

File: frontend/src/lib/ghost.ts

// Ghost API client for Astro
// Handles:
// - Post fetching and filtering
// - Author information retrieval
// - Tag-based content organization
// - Image URL processing
// - Content metadata extraction

Content Types Supported

Posts - Blog articles with tags and authors
Pages - Static pages (About, Services, etc.)
Authors - Team member profiles
Tags - Content categorization
Settings - Site-wide configuration

🗄️ Database Layer - MySQL

MySQL Configuration

Setting	Value	Purpose
Version	8.0	Latest stable release
Port	3306	Standard MySQL port
Container	`tessera-mysql`	Docker container identifier
Auth Plugin	mysql_native_password	Password authentication

Database Schema

Database: ghost
├── posts
│   ├── id (int, primary key)
│   ├── uuid (varchar, unique)
│   ├── title (varchar)
│   ├── slug (varchar, unique index)
│   ├── html (longtext)
│   ├── plaintext (longtext)
│   ├── feature_image (varchar)
│   ├── status (enum: draft, published, scheduled)
│   ├── created_at (datetime)
│   ├── updated_at (datetime)
│   └── published_at (datetime)
│
├── authors
│   ├── id (int, primary key)
│   ├── name (varchar)
│   ├── slug (varchar, unique)
│   ├── bio (text)
│   ├── profile_image (varchar)
│   └── cover_image (varchar)
│
├── tags
│   ├── id (int, primary key)
│   ├── name (varchar)
│   ├── slug (varchar, unique)
│   ├── description (text)
│   └── feature_image (varchar)
│
├── posts_tags
│   ├── post_id (foreign key → posts)
│   └── tag_id (foreign key → tags)
│
├── posts_authors
│   ├── post_id (foreign key → posts)
│   └── author_id (foreign key → authors)
│
├── users
│   ├── id (int, primary key)
│   ├── name (varchar)
│   ├── email (varchar, unique)
│   ├── password (varchar, hashed)
│   ├── role (enum: Owner, Admin, Editor, Author)
│   └── status (enum: active, inactive)
│
└── settings
    ├── key (varchar, primary key)
    └── value (longtext)

MySQL Health Check

# Docker health check configuration
Test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p{PASSWORD}"]
Interval: 10 seconds
Timeout: 5 seconds
Retries: 5 attempts
Start Period: 30 seconds (grace period for initialization)

Data Persistence

volumes:
  mysql_data:
    driver: local
    mount_path: /var/lib/mysql
    
  ghost_content:
    driver: local
    mount_path: /var/lib/ghost/content

Backup & Recovery

Strategy: Volume-based backups using Docker volumes

# Backup MySQL data
docker run --rm \
  -v tessera-mysql_data:/data \
  -v $(pwd)/backups:/backup \
  mysql:8.0 \
  mysqldump -h mysql -u ghost -p{PASSWORD} ghost > /backup/ghost.sql

# Restore from backup
docker exec tessera-mysql mysql -u ghost -p{PASSWORD} ghost < ./backups/ghost.sql

🐳 Docker & Web Services

Docker Orchestration

File: docker/docker-compose.yml Docker Compose manages two primary services interconnected through a custom bridge network.

Service Architecture

Service Dependencies

Ghost depends on MySQL being healthy before starting:

depends_on:
  mysql:
    condition: service_healthy    # waits for health check to pass

This ensures:

MySQL container starts first
Successfully initializes from init.sql
Passes 5 consecutive health checks
Only then Ghost container starts

Network Configuration

networks:
  tessera-network:
    driver: bridge

# Ghost can reach MySQL at: mysql:3306
# Frontend can reach Ghost at: http://localhost:2368
# External access via localhost ports mapping

Environment Variables & Secrets

Critical: Store in .env file (not in version control)

# .env (DO NOT COMMIT)
MYSQL_ROOT_PASSWORD=rootpassword
MYSQL_PASSWORD=ghostpassword

Defaults: If not provided, defaults are used:

MYSQL_ROOT_PASSWORD=rootpassword
MYSQL_PASSWORD=ghostpassword

Starting Services

# Start all services
docker-compose -f docker/docker-compose.yml up -d

# View logs
docker-compose -f docker/docker-compose.yml logs -f ghost
docker-compose -f docker/docker-compose.yml logs -f mysql

# Stop services
docker-compose -f docker/docker-compose.yml down

# Remove volumes (CAUTION: Data loss)
docker-compose -f docker/docker-compose.yml down -v

Container Health Status

# Check container status
docker ps

# Expected output:
# tessera-ghost     ghost:5-alpine      Up 2 hours    2368→2368
# tessera-mysql     mysql:8.0           Up 2 hours    3306→3306

# Check health
docker inspect tessera-mysql --format='{{.State.Health.Status}}'
# Output: healthy | unhealthy | none

🔄 Data Flow & Integration

Request Flow: User Accessing Website

Content Update Workflow

API Integration Layer

File: frontend/src/lib/ghost.ts

// Astro component integration pattern
---
import { getGhostPosts } from "@/lib/ghost";

// Built at static generation time (zero runtime overhead)
const posts = await getGhostPosts({
  limit: 10,
  include: ["authors", "tags"],
  filter: "status:published"
});
---

<div class="posts-grid">
  {posts.map(post => (
    <article>
      <h2>{post.title}</h2>
      <img src={post.feature_image} alt={post.title} />
      <!-- Rendered to static HTML at build time -->
    </article>
  ))}
</div>

🚀 Deployment Architecture

Development Environment

Local Machine
├── Astro Dev Server: http://localhost:4321
├── Ghost CMS: http://localhost:2368
├── MySQL: localhost:3306
└── Docker Network: tessera-network

Production Environment

Production Infrastructure
├── Frontend
│   ├── Static Host/CDN
│   │   ├── Vercel / Netlify / AWS S3 + CloudFront
│   │   └── dist/ folder deployed
│   └── Build Process
│       └── npm run build (generates static HTML)
│
├── Backend
│   ├── Ghost CMS Container
│   │   └── Docker/Kubernetes cluster
│   └── Domain: ghost.ypym.app:2368
│
└── Database
    ├── MySQL RDS / Managed Service
    └── Automatic backups & high availability

Build & Deployment Pipeline

Production Checklist

Set proper Ghost URL: https://ghost.ypym.app
Configure MySQL backups & replication
Enable HTTPS/TLS certificates
Set environment variables in .env
Configure content image CDN
Set up monitoring & alerting
Configure Ghost backup plugins
Test disaster recovery procedures

📊 Performance Metrics

Frontend Performance

Metric	Target	Current
Lighthouse Score	100	~98-100
Page Load	< 1s	~0.3-0.7s
First Contentful Paint	< 2.5s	~0.5s
Largest Contentful Paint	< 4s	~1.2s
Cumulative Layout Shift	< 0.1	~0.01

Optimization Features

Static Generation: Pre-rendered HTML (zero runtime overhead)
Image Optimization: Automatic WebP generation, lazy loading
Code Splitting: Per-route JavaScript bundles
CSS Purging: Only ship used styles (~15KB gzipped)
Minification: Automatic HTML, CSS, JS minification

🔐 Security Considerations

Frontend Security

No backend exposure: Static files only
CSP Headers: Configure in hosting provider
CORS: Not applicable (static site)
Image domains whitelisted: Only approved sources

Backend Security

Ghost Role-Based Access: Owner → Admin → Editor → Author
API Key Separation: Content API key ≠ Admin API key
Database Credentials: Stored in environment variables (.env)
Network Isolation: MySQL only accessible via Ghost (Docker network)

Secrets Management

# DON'T commit to git:
- .env
- .env.local
- docker-compose.override.yml

# DO commit:
- docker-compose.yml (with ${VAR} placeholders)
- .env.example (template with dummy values)

🛠️ Troubleshooting Guide

Common Issues

Ghost Cannot Connect to MySQL

# Check MySQL health
docker inspect tessera-mysql --format='{{.State.Health.Status}}'

# Check logs
docker logs tessera-mysql

# Restart services
docker-compose down && docker-compose up -d

Build Fails with Image Optimization

# Clear image cache
rm -rf frontend/.astro/

# Rebuild with verbose output
npm run build -- --verbose

# Check Sharp configuration
npm ls sharp

Content Not Appearing on Frontend

# Verify Ghost API is running
curl http://localhost:2368/ghost/api/v3/content/posts/?key=YOUR_API_KEY

# Check Ghost logs
docker logs tessera-ghost

# Verify database has content
docker exec tessera-mysql mysql -u ghost -p ghost -e "SELECT COUNT(*) FROM posts;"

📚 Additional Resources

Astro Documentation: https://docs.astro.build
Ghost Content API: https://ghost.org/docs/api/content/
Tailwind CSS: https://tailwindcss.com/docs
Docker Documentation: https://docs.docker.com
MySQL 8.0: https://dev.mysql.com/doc/refman/8.0/en/

📝 Summary

The YPYM Company platform is built on a modern, scalable architecture:

Frontend: Static-first Astro SSG with optimized images and component library
Backend: Headless Ghost CMS for content management without vendor lock-in
Database: MySQL 8.0 for robust relational data storage
Infrastructure: Docker orchestration for reproducible deployments
Performance: Sub-1 second page loads with 100 Lighthouse scores

This architecture balances developer experience, performance, maintainability, and scalability.

Documentation

​YPYM Company - Complete Architecture Documentation

​🏗️ System Architecture Overview

​Folder Structure Project

​Architecture Diagram

​🎨 Frontend Architecture

​Technology Stack

​Directory Structure

​Build Process

​Key Frontend Features

​1. Image Optimization Engine

​2. TypeScript Configuration

​3. Tailwind CSS Design System

​4. Site Configuration

​Development Commands

​👻 Backend Architecture

​Ghost CMS Overview

​Ghost Architecture Diagram

​Ghost API Endpoints

​Content API (Public)

​Admin API (Authenticated)

​Ghost Environment Configuration

​Ghost Docker Configuration

​Ghost Frontend Integration

​Content Types Supported

​🗄️ Database Layer - MySQL

​MySQL Configuration

​Database Schema

​MySQL Health Check

​Data Persistence

​Backup & Recovery

​🐳 Docker & Web Services

​Docker Orchestration

​Service Architecture

​Service Dependencies

​Network Configuration

​Environment Variables & Secrets

​Starting Services

​Container Health Status

​🔄 Data Flow & Integration

​Request Flow: User Accessing Website

​Content Update Workflow

​API Integration Layer

​🚀 Deployment Architecture

​Development Environment

​Production Environment

​Build & Deployment Pipeline

​Production Checklist

​📊 Performance Metrics

​Frontend Performance

​Optimization Features

​🔐 Security Considerations

​Frontend Security

​Backend Security

​Secrets Management

​🛠️ Troubleshooting Guide

​Common Issues

​Ghost Cannot Connect to MySQL

​Build Fails with Image Optimization

​Content Not Appearing on Frontend

​📚 Additional Resources

​📝 Summary