UI Architecture Strategy

TendSocial uses a 3-Tier UI Architecture to ensure maintainability, testability, and separation of concerns.

The 3 Tiers

1. Application Layer (@tendsocial/frontend)

• What is it?: The actual SaaS application (Next.js/Vite/Fastify).
• Responsibility: Business logic, page layouts, data fetching.
• Rule: It never knows about @heroui/react or @radix-ui directly. It only talks to @tendsocial/ui.

2. Facade Layer (@tendsocial/ui)

• What is it?: A thin package that acts as the public API for our Design System.
• Responsibility:
  • Exposing the "approved" list of components.
  • Holding global shared assets (e.g., Logo, Icons).
  • Providing a stable import path (import { ... } from '@tendsocial/ui') that never changes, even if we switch the underlying library.

3. Implementation Layer (@tendsocial/heroui3)

• What is it?: The heavy-lifting package that wraps the third-party library.
• Current Tech: HeroUI v3 (Beta).
• Responsibility:
  • Handling the "messy" parts of library integration.
  • Adapting APIs: Transforming strict or verbose 3rd-party APIs into developer-friendly ones (e.g., aliasing Context-based items).
  • Theming: Importing and configuring tailwind-variants or CSS.

Dependency Flow

graph TD
    A[Frontend App] -->|Imports| B(@tendsocial/ui)
    B -->|Exports| C(@tendsocial/heroui3)
    C -->|Wraps| D[HeroUI / React Aria]
    
    A -.->|❌ FORBIDDEN| C
    A -.->|❌ FORBIDDEN| D