پرش به محتویات

معماری Frontend وب

Frontend یک Application مبتنی بر Next.js App Router با Vertical Sliceهای Feature است. Server Component حالت پیش‌فرض است و Client Boundary فقط نزدیک تعامل، Browser API یا State قرار می‌گیرد.

ساختار Source

src/
├── app/       # URL، Layout، Metadata و Composition
├── features/  # Behavior، UI، Query، State و Adapter هر Feature
└── shared/    # Primitive پایدار و بدون دانش Feature

Feature در صورت نیاز واقعی می‌تواند domain، application، ports، adapters، queries، model، server و ui داشته باشد. Layer یا پوشه خالی برای تقارن ساخته نمی‌شود.

جهت Dependency

  • app فقط Public API از features و shared را Compose می‌کند.
  • Feature می‌تواند به Domain خود و shared وابسته باشد.
  • Feature دیگر فقط از Entry Point عمومی Import می‌شود و Deep Import ممنوع است.
  • shared از features و app مستقل است.
  • Domain به React، Next.js، TanStack Query، Zustand، Browser API یا Transport وابسته نیست.

Server، Client و BFF

flowchart LR Browser[Browser] -->|Same-origin| BFF[Next.js Route Handler] Server[Server Component] --> Adapter[Server Adapter] BFF --> Adapter Adapter -->|OpenAPI Contract| API[Tripylon Backend]
  • Server Component مستقیم Adapter سرور را فراخوانی می‌کند و برای Data به Route Handler داخلی Fetch نمی‌زند.
  • Client Component فقط از BFF هم‌مبدا استفاده می‌کند.
  • BFF Header حساس Backend را عبور نمی‌دهد و فقط داده لازم Client را برمی‌گرداند.
  • Authentication Check خوش‌بینانه Frontend جای Authorization Backend را نمی‌گیرد.
  • Cookie Session باید HttpOnly، Secure و دارای SameSite مناسب باشد.

مالکیت State

نوع State مالک
Server State و Cache شبکه TanStack Query
UI State مشترک و محدود Feature Zustand
State ساده Component و Form React State
URL قابل اشتراک و Filter Search Params و Router
Session و Permission نهایی Backend؛ Frontend فقط Projection امن

با تغییر Building فعال، Query Key و State وابسته باید Scope، Cancel یا Invalidate شوند تا داده Tenant قبلی نمایش داده نشود. Persist کردن State حساس به‌صورت پیش‌فرض ممنوع است.

Error و شبکه ضعیف

  • ورودی شبکه unknown است و در Boundary Parse می‌شود.
  • Error عمومی Code پایدار و Request ID دارد و Stack، Token، PII یا URL خصوصی را نمایش نمی‌دهد.
  • Query فقط خطای گذرا را محدود Retry می‌کند؛ Mutation به‌صورت پیش‌فرض Retry خودکار ندارد.
  • هر Flow دارای Loading، Empty، Error، Offline و Success روشن است.
  • Retry Command فقط با Idempotency و Policy تاییدشده انجام می‌شود.

Performance و Accessibility

  • Client Boundary، Dependency سنگین و Animation باید نیاز قابل سنجش داشته باشند.
  • لیست بلند Pagination یا Virtualization و تصویر ابعاد مشخص دارد.
  • Prefetch پرهزینه روی شبکه ضعیف محدود می‌شود.
  • Keyboard، Focus، Label، Contrast، Reduced Motion و Screen Reader بخشی از Acceptance Criteria هستند.

آزمون

Domain و Policy با Unit Test، Component تعاملی با Testing Library و Flow حیاتی Server/Client با Integration یا E2E پوشش داده می‌شود. Test نباید Network واقعی، Clock واقعی یا State باقی‌مانده Test قبلی را فرض کند.