front-end-dev-standards 1.0.0 → 1.1.0

package/standards//360/237/247/261 architecture.md"

@@ -0,0 +1,654 @@
+# Architecture Standards
+
+Version: 1.0
+Target: Angular 20+
+Architecture Style: Feature-Based + Domain-Driven Design (DDD)
+Applies To: All HRMS Frontend Applications
+
+---
+
+# 1. Architecture Principles
+
+## Core Principles
+
+1. Feature First Organization
+2. Domain Driven Design
+3. Standalone Angular Architecture
+4. Signals First State Management
+5. Unidirectional Data Flow
+6. Dependency Rule Enforcement
+7. Lazy Loading by Default
+8. Shared Code by Exception
+9. Security by Design
+10. Scalability Over Convenience
+
+---
+
+# 2. Architecture Overview
+
+```text
+┌─────────────────────────────────┐
+│            APP SHELL            │
+│ Header | Sidebar | Layout       │
+└─────────────────────────────────┘
+                │
+                ▼
+┌─────────────────────────────────┐
+│           FEATURES              │
+│ Employees | Payroll | Leaves    │
+│ Attendance | Recruitment        │
+└─────────────────────────────────┘
+                │
+                ▼
+┌─────────────────────────────────┐
+│             SHARED              │
+│ Components | Pipes | Directives │
+└─────────────────────────────────┘
+                │
+                ▼
+┌─────────────────────────────────┐
+│              CORE               │
+│ Auth | API | Guards | Logging   │
+└─────────────────────────────────┘
+```
+
+---
+
+# 3. Folder Structure
+
+```text
+src/
+├── app/
+│
+├── core/
+│   ├── auth/
+│   ├── guards/
+│   ├── interceptors/
+│   ├── services/
+│   ├── config/
+│   └── constants/
+│
+├── shared/
+│   ├── ui/
+│   ├── directives/
+│   ├── pipes/
+│   ├── models/
+│   ├── utils/
+│   └── validators/
+│
+├── features/
+│   ├── employees/
+│   ├── attendance/
+│   ├── payroll/
+│   ├── recruitment/
+│   ├── leaves/
+│   └── timesheet/
+│
+├── layout/
+│   ├── header/
+│   ├── sidebar/
+│   ├── footer/
+│   └── shell/
+│
+├── assets/
+├── environments/
+└── styles/
+```
+
+---
+
+# 4. Feature Structure
+
+Each feature is a complete vertical slice.
+
+```text
+features/timesheet/
+
+├── pages/
+│   ├── timesheet-list/
+│   ├── timesheet-detail/
+│   └── timesheet-create/
+│
+├── components/
+│   ├── timesheet-calendar/
+│   ├── timesheet-preview/
+│   └── weekly-summary/
+│
+├── services/
+│   ├── timesheet.service.ts
+│   └── timesheet-store.service.ts
+│
+├── models/
+│   ├── timesheet.model.ts
+│   ├── create-timesheet-request.ts
+│   └── timesheet-filter.ts
+│
+├── guards/
+│
+├── resolvers/
+│
+├── timesheet.routes.ts
+└── index.ts
+```
+
+---
+
+# 5. Dependency Rules
+
+## Allowed
+
+```text
+Feature
+  ├── Shared
+  ├── Core
+  └── Angular Framework
+```
+
+## Forbidden
+
+```text
+Feature A ───► Feature B
+```
+
+```text
+Shared ───► Feature
+```
+
+```text
+Core ───► Feature
+```
+
+---
+
+# 6. Layer Responsibilities
+
+## Core Layer
+
+Application-wide infrastructure.
+
+Contains:
+
+* Authentication
+* Authorization
+* Interceptors
+* Logging
+* Global Configuration
+* Feature Flags
+* Notification Services
+
+Never Contains:
+
+* Business Logic
+* Feature Components
+* Domain Models
+
+---
+
+## Shared Layer
+
+Reusable UI Building Blocks.
+
+Contains:
+
+* Buttons
+* Tables
+* Dialogs
+* Pipes
+* Validators
+* Utility Functions
+
+Must Be:
+
+* Stateless
+* Generic
+* Feature Independent
+
+Never Contains:
+
+* Feature Services
+* API Calls
+* Feature Models
+
+---
+
+## Feature Layer
+
+Business functionality.
+
+Contains:
+
+* Pages
+* Components
+* Services
+* Models
+* Routes
+
+Must Own:
+
+* Feature State
+* Feature API Logic
+* Feature UI
+
+---
+
+# 7. Smart vs Presentational Components
+
+## Smart Components
+
+Responsibilities:
+
+* Data Fetching
+* Service Interaction
+* State Management
+* Navigation
+
+Example:
+
+```typescript
+export class EmployeeListPage {
+  private readonly employeeService =
+    inject(EmployeeService);
+
+  readonly employees =
+    signal<Employee[]>([]);
+}
+```
+
+Naming:
+
+```text
+employee-list.page.ts
+employee-detail.page.ts
+```
+
+---
+
+## Presentational Components
+
+Responsibilities:
+
+* Rendering
+* User Interaction
+* Event Emission
+
+Example:
+
+```typescript
+export class EmployeeCardComponent {
+  readonly employee =
+    input.required<Employee>();
+
+  readonly selected =
+    output<Employee>();
+}
+```
+
+Must Not:
+
+* Inject Feature Services
+* Perform API Calls
+
+---
+
+# 8. State Management Strategy
+
+## Level 1
+
+Component Signals
+
+```typescript
+readonly loading = signal(false);
+readonly employees = signal<Employee[]>([]);
+```
+
+Default choice.
+
+---
+
+## Level 2
+
+Feature Store
+
+```typescript
+EmployeeStore
+AttendanceStore
+PayrollStore
+```
+
+Use when state is shared within a feature.
+
+---
+
+## Level 3
+
+Global Store
+
+Use only when:
+
+* Shared across multiple features
+* Complex orchestration required
+
+Examples:
+
+* User Session
+* Permissions
+* Global Settings
+
+---
+
+# 9. Data Flow Rules
+
+```text
+API
+ │
+ ▼
+Service
+ │
+ ▼
+Store / Signal
+ │
+ ▼
+Page Component
+ │
+ ▼
+Presentational Component
+```
+
+Data Flow:
+
+Top Down
+
+Events Flow:
+
+Bottom Up
+
+No Circular Communication.
+
+---
+
+# 10. API Layer Architecture
+
+## Service Pattern
+
+```typescript
+EmployeeService
+PayrollService
+AttendanceService
+```
+
+Responsibilities:
+
+* API Calls
+* DTO Mapping
+* Response Transformation
+
+Never:
+
+* UI Logic
+* Component State
+
+---
+
+# 11. DTO Strategy
+
+Separate Models
+
+```typescript
+Employee
+CreateEmployeeRequest
+UpdateEmployeeRequest
+EmployeeResponse
+EmployeeViewModel
+```
+
+Never reuse API models directly in complex UI.
+
+Map API models to ViewModels.
+
+---
+
+# 12. Routing Architecture
+
+## Rules
+
+Every Feature Owns Routes
+
+```text
+employees.routes.ts
+payroll.routes.ts
+attendance.routes.ts
+```
+
+All Features Lazy Loaded
+
+```typescript
+loadChildren()
+loadComponent()
+```
+
+No Eager Feature Loading.
+
+---
+
+# 13. Layout Architecture
+
+```text
+Shell
+ ├── Header
+ ├── Sidebar
+ ├── Content
+ └── Footer
+```
+
+Responsibilities:
+
+* Navigation
+* User Context
+* Responsive Layout
+
+Must Not:
+
+* Feature Logic
+
+---
+
+# 14. Shared Component Guidelines
+
+Promote to Shared only when:
+
+Used in 2+ Features
+
+Examples:
+
+```text
+DataTable
+PageHeader
+ConfirmDialog
+LoadingSpinner
+```
+
+Not Shared:
+
+```text
+EmployeeCard
+PayrollSummary
+TimesheetCalendar
+```
+
+These belong to features.
+
+---
+
+# 15. Scalability Rules
+
+Split Feature When:
+
+* More than 20 Components
+* Multiple Domains
+* Independent Release Cycle
+
+Example:
+
+```text
+Recruitment
+ ├── Candidates
+ ├── Interviews
+ └── Job Openings
+```
+
+Can become separate features.
+
+---
+
+# 16. Micro Frontend Readiness
+
+Features must be:
+
+* Self Contained
+* Independently Deployable
+* Loosely Coupled
+
+Avoid direct feature imports.
+
+---
+
+# 17. Security Architecture
+
+All requests pass through:
+
+```text
+Auth Interceptor
+Error Interceptor
+Audit Interceptor
+```
+
+Responsibilities:
+
+* Token Injection
+* Error Handling
+* Logging
+
+Never bypass interceptors.
+
+---
+
+# 18. Caching Strategy
+
+Allowed:
+
+```typescript
+signal()
+computed()
+shareReplay()
+```
+
+Use for:
+
+* Reference Data
+* Lookup Lists
+* User Preferences
+
+Avoid duplicate API calls.
+
+---
+
+# 19. Performance Architecture
+
+Mandatory:
+
+* Lazy Loaded Features
+* OnPush Components
+* Signals
+* Route Level Code Splitting
+* Track Functions
+* Virtual Scrolling for Large Lists
+
+---
+
+# 20. Testing Architecture
+
+Co-Locate Tests
+
+```text
+employee.service.ts
+employee.service.spec.ts
+```
+
+Coverage Targets:
+
+* Services > 90%
+* Components > 80%
+* Critical Business Logic > 95%
+
+---
+
+# 21. Monorepo Readiness
+
+Future Structure
+
+```text
+apps/
+  hrms/
+
+libs/
+  shared-ui/
+  shared-utils/
+  auth/
+  employees/
+  payroll/
+```
+
+Architecture should support migration to Nx without major refactoring.
+
+---
+
+# 22. Architectural Decision Records
+
+Major architectural changes require ADRs.
+
+```text
+docs/adr/
+
+001-use-signals.md
+002-feature-based-architecture.md
+003-ngrx-adoption.md
+```
+
+Document:
+
+* Problem
+* Decision
+* Alternatives
+* Consequences
+
+---
+
+# 23. Definition of Architectural Compliance
+
+A feature is architecture compliant when:
+
+✓ Standalone Components
+
+✓ Feature-Based Structure
+
+✓ Signals First
+
+✓ Lazy Loaded
+
+✓ No Cross Feature Imports
+
+✓ Shared Components Reusable
+
+✓ API Calls Through Services
+
+✓ OnPush Everywhere
+
+✓ Typed Models
+
+✓ Tests Included
+
+✓ Security Reviewed
+
+✓ Performance Reviewed
+
+✓ Accessibility Verified