diff --git a/README_AUTONOMY.md b/README_AUTONOMY.md index 8a4c033..6c9baed 100644 --- a/README_AUTONOMY.md +++ b/README_AUTONOMY.md @@ -19,6 +19,16 @@ This repository utilizes a fully autonomous pipeline to generate professional ma - **Motion:** Veo 3 (5s High-Fidelity Teasers). - **Persistence:** Google Cloud Storage (Public CDN). - **Distribution:** Buffer API (via JSON payload). + +### Structural Comparison: Manual vs Autonomous Content Generation + +| Feature | Manual Content Creation | Autonomous Engine (Vibe Coding) | +| :--- | :--- | :--- | +| **Speed** | Days/Weeks | Minutes (triggered on release) | +| **Cost** | High (Human labor) | Low (API credits) | +| **Consistency**| Variable (depends on human focus) | Absolute (deterministic prompt structures) | +| **Scalability** | Low | Infinite (parallel generation) | + ## Efficiency & Credits Monitoring ($300) To maximize the value of the $300 Google Cloud free tier/credits, follow these best practices: diff --git a/architectures/backend-for-frontend/readme.md b/architectures/backend-for-frontend/readme.md index c685536..e9bd8e8 100644 --- a/architectures/backend-for-frontend/readme.md +++ b/architectures/backend-for-frontend/readme.md @@ -27,7 +27,16 @@ This engineering directive defines the **best practices** for the Backend-For-Fr - 🛠️ [**Implementation Guide:** Code patterns and Anti-patterns](./implementation-guide.md) -## Architecture Diagram + +### Structural Comparison: Backend-for-Frontend (BFF) vs API Gateway + +| Feature | Backend-for-Frontend (BFF) | API Gateway | +| :--- | :--- | :--- | +| **Scope** | One per specific client type (Web, Mobile, Desktop) | Single entry point for all clients | +| **Ownership** | Owned by the Frontend team | Owned by a dedicated API or Platform team | +| **Customization** | Highly tailored to client UI needs | Generic, serving broad needs | +| **Complexity** | Multiple BFFs to manage | Single point of failure/bottleneck | + ```mermaid graph TD @@ -49,6 +58,7 @@ graph TD class BFF_Mobile component; ``` + ## Core Principles 1. **Client Focus:** Each BFF is built and maintained by the same team that builds the frontend client. diff --git a/architectures/event-driven-architecture/readme.md b/architectures/event-driven-architecture/readme.md index 380b6f4..39275ca 100644 --- a/architectures/event-driven-architecture/readme.md +++ b/architectures/event-driven-architecture/readme.md @@ -32,6 +32,17 @@ To deeply understand the nuances of EDA, consult the following specialized modul - ⚖️ [**Trade-offs:** Pros, Cons, and System Constraints](./trade-offs.md) - 🛠️ [**Implementation Guide:** Code patterns and Anti-patterns](./implementation-guide.md) --- + +### Structural Comparison: Event-Driven vs Request-Response + +| Feature | Event-Driven Architecture | Request-Response (REST/RPC) | +| :--- | :--- | :--- | +| **Coupling** | Loose (Producers don't know consumers) | Tight (Client knows server address) | +| **Communication** | Asynchronous | Synchronous (usually) | +| **Resilience** | High (Messages can be queued if consumer is down) | Lower (Fails if server is down) | +| **Scalability** | Excellent (Easy to add new consumers) | Good (Requires load balancing) | +| **Complexity** | High (Eventual consistency, tracking flows) | Low (Straightforward flows) | + ## Core Principles 1. **Asynchronous by Default:** Synchronous RPC (REST/gRPC) is restricted only to immediate read-queries or initial gateway ingress. All inter-service state mutations must occur asynchronously. diff --git a/architectures/feature-sliced-design/readme.md b/architectures/feature-sliced-design/readme.md index 0c045b9..6f81e98 100644 --- a/architectures/feature-sliced-design/readme.md +++ b/architectures/feature-sliced-design/readme.md @@ -18,6 +18,16 @@ last_updated: 2026-03-22 This engineering directive contains strict architectural guidelines and 20 practical patterns for using the Feature-Sliced Design methodology to build scalable and deterministic Frontend applications. + +### Structural Comparison: Feature-Sliced Design vs Clean Architecture + +| Feature | Feature-Sliced Design (FSD) | Clean Architecture | +| :--- | :--- | :--- | +| **Primary Focus** | Business Domains & Features | Separation of Concerns & Layers | +| **Coupling** | Low (Cross-feature imports forbidden) | Low (Dependencies point inward) | +| **Learning Curve** | High (Strict structural rules) | High (Abstract concepts) | +| **Scalability** | Excellent for large frontend teams | Excellent for complex enterprise backends | + ## Map of Patterns - 📊 [**Data Flow:** Request and Event Lifecycle](./data-flow.md) - 📁 [**Folder Structure:** Layering publisher/subscriber logic](./folder-structure.md) diff --git a/architectures/hexagonal-architecture/readme.md b/architectures/hexagonal-architecture/readme.md index 45572ea..dd3f167 100644 --- a/architectures/hexagonal-architecture/readme.md +++ b/architectures/hexagonal-architecture/readme.md @@ -28,6 +28,18 @@ This pattern documentation has been decomposed into specialized modules for zero - 📁 **[Folder Structure](./folder-structure.md):** The strict directory blueprints. - ⚖️ **[Trade-offs](./trade-offs.md):** Pros, cons, and architectural constraints. - 🛠️ **[Implementation Guide](./implementation-guide.md):** Step-by-step rules and code constraints for Vibe Coding. + +```mermaid +flowchart TD + A[External System/User] -->|Calls Port| B(Adapter) + B -->|Implements Port| C{Domain Logic} + C -->|Requires Port| D(Adapter) + D -->|Talks to| E[Database/External API] + + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + class A,B,C,D,E default; +``` + ## 🚀 The Core Philosophy Hexagonal Architecture (Ports & Adapters) ensures the core business logic is isolated from specific external technologies. diff --git a/architectures/micro-frontends/folder-structure.md b/architectures/micro-frontends/folder-structure.md index b4b9590..2e5133a 100644 --- a/architectures/micro-frontends/folder-structure.md +++ b/architectures/micro-frontends/folder-structure.md @@ -44,5 +44,16 @@ workspace/ │ └── event-bus/ (Agnostic communication contract types) ``` + + +### Structural Comparison: Monorepo vs Polyrepo for MFEs + +| Feature | Monorepo (Workspace) | Polyrepo (Independent Repos) | +| :--- | :--- | :--- | +| **Code Sharing** | Easy (via local packages) | Hard (requires publishing to npm) | +| **Dependency Management** | Centralized (Single source of truth) | Decentralized (Version conflicts likely) | +| **CI/CD Complexity** | High (Requires smart build tools like Nx/Turborepo) | Low (Standard pipelines per repo) | +| **Autonomy** | Medium (Shared tooling constraints) | High (Total independence) | + #### 🚀 Solution Structure your repository (whether mono or polyrepo) to ensure each application folder (`mfe-*`) operates as a completely standalone entity. Shared libraries must be restricted strictly to agnostic utilities and purely visual design system components. Ensure zero business logic crossover. diff --git a/architectures/microservices/readme.md b/architectures/microservices/readme.md index 4ba8c4a..b62f624 100644 --- a/architectures/microservices/readme.md +++ b/architectures/microservices/readme.md @@ -23,6 +23,16 @@ This engineering directive defines the **best practices** for the Microservices - 📁 [**Folder Structure:** Layering logic](./folder-structure.md) - ⚖️ [**Trade-offs:** Pros, Cons, and System Constraints](./trade-offs.md) - 🛠️ [**Implementation Guide:** Code patterns and Anti-patterns](./implementation-guide.md) + +### Structural Comparison: Microservices vs SOA (Service-Oriented Architecture) + +| Feature | Microservices | SOA | +| :--- | :--- | :--- | +| **Component Size** | Small, single-purpose | Larger, enterprise-wide services | +| **Communication** | Dumb pipes (REST, lightweight messaging) | Smart pipes (Enterprise Service Bus - ESB) | +| **Data Storage** | Database per service (Strict isolation) | Often shares data storage | +| **Coupling** | Loosely coupled | Moderately to tightly coupled | + ## Core Principles 1. **Isolation & Testability:** Changing a single feature doesn't break the entire business process. diff --git a/architectures/monolithic-architecture/readme.md b/architectures/monolithic-architecture/readme.md index 00db8c5..cd73576 100644 --- a/architectures/monolithic-architecture/readme.md +++ b/architectures/monolithic-architecture/readme.md @@ -23,6 +23,17 @@ last_updated: 2026-03-22 - 📁 [**Folder Structure:** Layering logic](./folder-structure.md) - ⚖️ [**Trade-offs:** Pros, Cons, and System Constraints](./trade-offs.md) - 🛠️ [**Implementation Guide:** Code patterns and Anti-patterns](./implementation-guide.md) + +### Structural Comparison: Monolithic Architecture vs Microservices + +| Feature | Monolithic Architecture | Microservices | +| :--- | :--- | :--- | +| **Deployment** | Single unit (all or nothing) | Independent per service | +| **Scalability** | Scale the whole application | Scale specific components | +| **Technology Stack** | Uniform (hard to change) | Diverse (easy to adopt new tech) | +| **Complexity** | Lower initially, higher as it grows | Higher initially, manageable at scale | +| **Data Management** | Shared database | Database per service | + ## Core Principles 1. **Isolation & Testability:** Changing a single feature doesn't break the entire business process. diff --git a/backend/mongodb/database-optimization.md b/backend/mongodb/database-optimization.md index 8e5d14e..0996653 100644 --- a/backend/mongodb/database-optimization.md +++ b/backend/mongodb/database-optimization.md @@ -34,6 +34,15 @@ Create indexes following the ESR rule: 2. **S**ort fields next. 3. **R**ange fields last. +```mermaid +graph LR + A[Equality Fields] --> B[Sort Fields] + B --> C[Range Fields] + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + class A,B,C default; +``` + + ### 🚀 Solution ```javascript diff --git a/backend/mongodb/security-best-practices.md b/backend/mongodb/security-best-practices.md index c5b477b..1fd3032 100644 --- a/backend/mongodb/security-best-practices.md +++ b/backend/mongodb/security-best-practices.md @@ -28,6 +28,16 @@ db.createUser({ user: "appUser", pwd: "secretPassword", roles: ["root"] }) Enable authorization in `mongod.conf` (`security.authorization: enabled`) and create custom roles or use the principle of least privilege. + +### Structural Comparison: Role-Based Access Control (RBAC) vs Built-in Roles + +| Feature | Custom RBAC (Principle of Least Privilege) | Built-in Root/Admin Roles | +| :--- | :--- | :--- | +| **Security Risk** | Low (Access restricted to specific tasks) | Critical (Full system compromise possible) | +| **Granularity** | Collection and Action level | Database or System level | +| **Auditability** | High (Clear mapping of who did what) | Low (Generic roles obscure intent) | +| **Complexity** | High (Requires planning and maintenance) | Low (Easy but dangerous) | + ### 🚀 Solution ```javascript diff --git a/frontend/angular/readme.md b/frontend/angular/readme.md index 44dd16c..5ab17f9 100644 --- a/frontend/angular/readme.md +++ b/frontend/angular/readme.md @@ -34,6 +34,16 @@ The `@Input()` decorator operates outside the Signals reactivity system. Changes ```typescript title = input(''); ``` + +### Structural Comparison: Signals vs RxJS + +| Feature | Signals (`signal`, `computed`) | RxJS (`BehaviorSubject`, `Observable`) | +| :--- | :--- | :--- | +| **Execution** | Synchronous | Asynchronous (typically) | +| **State Tracking** | Automatic (granular dependency tracking) | Manual (subscriptions required) | +| **Complexity** | Low (simple getter/setter) | High (complex operator chains) | +| **Best For** | Synchronous UI state | Asynchronous events, complex streams | + ### 🚀 Solution Use Signal Inputs (`input()`). This allows Angular to precisely know *which* specific component requires an update, paving the way for Zoneless applications. --- diff --git a/frontend/angular/testing.md b/frontend/angular/testing.md index 70f6623..6d0a76d 100644 --- a/frontend/angular/testing.md +++ b/frontend/angular/testing.md @@ -55,6 +55,19 @@ it('should render incremented counter on click', async () => { expect(text).toContain('1'); }); ``` + +```mermaid +flowchart TD + A[Component Rendered] --> B{Action Triggered} + B --> C[Execute Component Logic] + C --> D{Evaluate State/Signal} + D --> E[DOM Update via Change Detection] + E --> F[Assert DOM or Component State] + + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + class A,B,C,D,E,F default; +``` + ### 🚀 Solution Always use `TestBed` to create the component. Simulate user interactions via the DOM, run `detectChanges()`, and assert against the rendered output to ensure both the signal and the template are synchronized correctly. diff --git a/frontend/javascript/testing.md b/frontend/javascript/testing.md index 28ade65..1ba4b2b 100644 --- a/frontend/javascript/testing.md +++ b/frontend/javascript/testing.md @@ -58,6 +58,16 @@ test('update user', () => { expect(user.name).toBe('Bob'); }); ``` + +### Structural Comparison: Unit Testing vs Integration Testing vs E2E + +| Feature | Unit Testing | Integration Testing | End-to-End (E2E) Testing | +| :--- | :--- | :--- | :--- | +| **Scope** | Single isolated function/component | Multiple connected units | Full application workflow | +| **Speed** | Extremely Fast (<1ms) | Fast to Medium | Slow (seconds to minutes) | +| **Cost to Write/Maintain**| Low | Medium | High | +| **Confidence Level** | Low (doesn't catch contract issues) | Medium | High (simulates real user) | + ### 🚀 Solution Ensure every test is fully isolated. Use `beforeEach` or setup functions to instantiate fresh state for every individual test case. diff --git a/frontend/react/performance.md b/frontend/react/performance.md index 81ddfd8..795a65d 100644 --- a/frontend/react/performance.md +++ b/frontend/react/performance.md @@ -50,6 +50,16 @@ function UserList({ users }) { ); } ``` + +### Structural Comparison: Manual Memoization vs React Compiler + +| Feature | Manual Memoization (`useMemo`, `useCallback`) | React Compiler | +| :--- | :--- | :--- | +| **Developer Experience** | High cognitive load (dependency arrays) | Zero config (automatic) | +| **Code Clarity** | Cluttered with hooks | Clean and declarative | +| **Bug Risk** | High (stale closures, missing deps) | Low (compiler-verified) | +| **Optimization** | Component-level only | Structural and deep | + ### 🚀 Solution Rely on the **React Compiler** (introduced in React 19+). The compiler automatically memoizes values and functions, meaning manual hooks are largely obsolete and code becomes purely declarative. This optimizes components structurally and removes manual dependency tracking overhead. diff --git a/frontend/react/state-management.md b/frontend/react/state-management.md index 67881db..ba5fcf9 100644 --- a/frontend/react/state-management.md +++ b/frontend/react/state-management.md @@ -62,6 +62,20 @@ function Form() { ); } ``` + +```mermaid +flowchart TD + A[Form Submitted] --> B{Action isPending?} + B -->|Yes| C[Disable Submit Button] + B -->|No| D[Process saveAction] + D --> E{Error occurred?} + E -->|Yes| F[Update Error State] + E -->|No| G[Action Successful] + + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + class A,B,C,D,E,F,G default; +``` + ### 🚀 Solution Use the `useActionState` Hook (React 19+) for seamless action state management. This hook natively handles loading and error states, resolves race conditions by ensuring only the latest action state is applied to the UI, and optimizes rendering cycles deterministically. diff --git a/frontend/typescript/objects-functions.md b/frontend/typescript/objects-functions.md index 57159aa..1beff2d 100644 --- a/frontend/typescript/objects-functions.md +++ b/frontend/typescript/objects-functions.md @@ -143,6 +143,16 @@ abstract class BaseService { log(msg: string) { console.log(msg); } } ``` + +### Structural Comparison: Abstract Classes vs Interfaces + +| Feature | Abstract Classes | Interfaces | +| :--- | :--- | :--- | +| **Implementation Logic** | Can provide default/shared implementation | Cannot provide implementation | +| **Multiple Inheritance** | No (Single inheritance only) | Yes (Can implement multiple) | +| **Runtime Presence** | Yes (Compiles to JS class) | No (Erased at compile time) | +| **Access Modifiers** | Supports public, protected, private | All members are public | + ### 🚀 Solution Utilize `abstract` classes when requiring shared implementation logic combined with strict contractual enforcement of specific methods by subclasses. ## 🚨 28. Private vs `#private`