Component Architecture - Three-Tier System

Date: October 11, 2025
Status: ✅ Implemented
Branch: feat/tailwind-integration

Overview

This monorepo uses a three-tier component architecture to organize UI code by reusability and scope:

1. MONOREPO-WIDE   (packages/ui/)              → Everyone uses
2. DIVISION-SPECIFIC (packages/ui-{division}/) → Division apps use
3. APP-SPECIFIC     (apps/{division}/{brand}/src/components/) → Single app uses

---

📂 Directory Structure

monorepo/
├── packages/                      # REUSABLE LIBRARIES
│   │
│   ├── ui/                        # Tier 1: Monorepo-wide
│   │   └── src/
│   │       └── components/
│   │           ├── Button/        # Generic button
│   │           ├── Input/         # Generic input
│   │           ├── Modal/         # Generic modal
│   │           ├── Slider/        # Generic slider
│   │           └── navigation/    # Base navigation primitives
│   │
│   ├── ui-stay-match/             # Tier 2: Stay Match division
│   │   └── src/
│   │       └── components/
│   │           ├── Hero/          # Stay Match hero pattern
│   │           └── Navigation/    # Stay Match navigation
│   │
│   ├── ui-guestroom/              # Tier 2: Guestroom division (future)
│   │   └── src/
│   │       └── components/
│   │
│   └── ui-homestay/               # Tier 2: Homestay division (future)
│       └── src/
│           └── components/
│
└── apps/                          # APPLICATIONS
    └── stay_match/
        └── pinkguest/
            ├── web/
            │   └── src/
            │       └── components/    # Tier 3: Pinkguest web only
            │
            ├── mobile/
            │   └── src/
            │       └── components/    # Tier 3: Pinkguest mobile only
            │
            └── shared/                # Brand assets (not components!)
                ├── assets/images/     # Images
                └── constants/         # Content/copy

---

🎯 When to Use Each Tier

Tier 1: Monorepo-Wide (packages/ui/)

Use when:

• Component is used across ALL divisions (Stay Match, Guestroom, Homestay, etc.)
• Zero business logic
• Pure presentation
• Generic and universal

Examples:

• Button - Every app needs buttons
• Input - Every app has inputs
• Modal - Every app shows modals
• Tooltip - Every app has tooltips
• Slider - Generic slider component
• Base navigation primitives (BottomNavigation, HorizontalTabs)

Package name: @cloudalt-frontend/ui

Import:

import { Button, Input, Modal } from '@cloudalt-frontend/ui';

---

Tier 2: Division-Specific (packages/ui-{division}/)

Use when:

• Component is used across multiple apps in one division
• Implements division-specific UI patterns
• Shared within division, not across divisions

Examples for Stay Match:

• Hero - Landing page hero (shared pattern across pinkguest, orangeguest, roomlgbt)
• StayMatchNavigation - Navigation specific to Stay Match apps
• SearchBar - Stay Match-specific search patterns
• ListingCard - How Stay Match shows listings

Examples for Guestroom (future):

• GuestroomHero - Different hero pattern than Stay Match
• GuestroomSearch - Different search UX

Package names:

• @cloudalt-frontend/ui-stay-match
• @cloudalt-frontend/ui-guestroom
• @cloudalt-frontend/ui-homestay

Import:

import { Hero, StayMatchNavigation } from '@cloudalt-frontend/ui-stay-match';

---

Tier 3: App-Specific (apps/{division}/{brand}/{platform}/src/components/)

Use when:

• Component is used ONLY in this specific app
• Has business logic specific to this app/platform
• Too unique to share

Examples for pinkguest web:

• PinkguestCheckoutFlow - Pinkguest-specific checkout
• PinkguestProfileSettings - Unique settings page
• PinkguestDashboard - Brand-specific dashboard

Examples for pinkguest mobile:

• MobileOnboarding - Mobile-specific onboarding flow
• CameraIntegration - Mobile camera features

Location:

• apps/stay_match/pinkguest/web/src/components/
• apps/stay_match/pinkguest/mobile/src/components/

Import:

// Direct relative import within the app
import { CheckoutFlow } from '../components/CheckoutFlow';

---

🌳 Decision Tree

Question: Where should this component live?

Is it used in multiple apps?
│
├─ NO ──→ apps/{division}/{brand}/{platform}/src/components/
│         (App-specific, keep it there)
│
└─ YES
   │
   └─ Is it used across divisions?
      │
      ├─ YES ──→ packages/ui/
      │         (Everyone needs it, make it generic)
      │
      └─ NO ──→ Multiple apps in same division?
         │
         └─ YES ──→ packages/ui-{division}/
                   (Division-specific pattern)

---

📊 Examples by Tier

Component	Tier	Package	Used By
Button	1	packages/ui/	All apps everywhere
Input	1	packages/ui/	All apps everywhere
Modal	1	packages/ui/	All apps everywhere
Hero	2	packages/ui-stay-match/	All Stay Match apps
StayMatchNavigation	2	packages/ui-stay-match/	All Stay Match apps
GuestroomHero	2	packages/ui-guestroom/	All Guestroom apps
CheckoutFlow	3	apps/stay_match/pinkguest/web/	Pinkguest web only
ProfileSettings	3	apps/stay_match/pinkguest/mobile/	Pinkguest mobile only

---

🚀 Best Practices

1. Start Specific, Extract When Needed

❌ DON’T:

Build Hero in packages/ui/ "because we might need it later"

✅ DO:

1. Build Hero in apps/stay_match/pinkguest/web/src/components/
2. Orangeguest needs it? → Extract to packages/ui-stay-match/
3. Guestroom needs similar? → They build their own in packages/ui-guestroom/
4. Everyone needs the pattern? → Extract common parts to packages/ui/

2. Don’t Prematurely Abstract

Only move components to packages when you have real duplication, not anticipated future use.

3. Division Boundaries are Real

Stay Match and Guestroom can have different implementations of similar components. Don’t force them to share unless truly generic.

4. Brand Assets ≠ Components

Brand-specific images and content go in apps/{division}/{brand}/shared/, not in packages.

---

🔄 Migration Path

When extracting a component from app to package:

1. Copy component to new package location
2. Update imports in the package
3. Update consuming apps to import from package
4. Test that everything still works
5. Delete original app-specific component
6. Update documentation

---

📝 Current Status

Implemented:

• ✅ packages/ui/ - Monorepo-wide components
• ✅ packages/ui-stay-match/ - Stay Match division package
• ✅ StayMatchNavigation migrated to ui-stay-match
• ✅ Hero component placeholder in ui-stay-match
• ✅ Brand assets structure: apps/stay_match/pinkguest/shared/

Future:

• ⏳ packages/ui-guestroom/ - When Guestroom apps need shared components
• ⏳ packages/ui-homestay/ - When Homestay apps need shared components
• ⏳ Extract more components to ui-stay-match as duplication emerges

---

Brand Assets (Special Case)

Icons and images that differ per brand belong in:

---

❓ FAQs

Q: Should generic components go in ui or ui-stay-match?
A: If ALL divisions will use it → packages/ui/. If only Stay Match → packages/ui-stay-match/.

Q: Can I import from ui-guestroom in a Stay Match app?
A: Technically yes, but don’t. Each division should be independent.

Q: What if pinkguest and orangeguest have slight variations of a component?
A: Put the shared pattern in ui-stay-match, pass brand-specific props or use design tokens for styling differences.

Q: Should I create ui-{division} packages for all divisions now?
A: No! Only create them when you have real components to share. Start with app-specific components first.

---

📚 Related Documentation

• Design Token System - How to use design tokens for styling
• Asset Management - Where to put images, icons, and fonts
• Tailwind Integration Guide - Using Tailwind with components
• Onboarding Guide - Getting started

---

Last Updated: October 11, 2025
Maintained By: Engineering Team