Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions .agents/rules/rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,8 @@ This Code of Conduct applies in the following scenarios:
---
## 🚨 Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers:
> [!IMPORTANT]
> Instances of abusive, harassing, or otherwise unacceptable behavior MUST be reported to the project maintainers:

- 📧 **Communication Method:** Please reach out directly to the project maintainers (via open issues for moderation, private messages, or public contacts found on their GitHub profiles).

Expand All @@ -142,7 +143,8 @@ Project maintainers will follow these Community Impact Guidelines in determining

This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

Answers to common questions about this code of conduct can be found in the official [FAQ](https://www.contributor-covenant.org/faq). Translations are available at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations).
> [!IMPORTANT]
> Answers to common questions about this code of conduct MUST be found in the official [FAQ](https://www.contributor-covenant.org/faq). Translations are available at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations).
---

<a name="russian"></a>
Expand Down
2 changes: 1 addition & 1 deletion .agents/rules/system-documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ graph TD
## 4. Documentation Quality Standards

When writing or updating **system documentation**, Jules must verify the following constraints:
- [ ] **Technical Easy English:** Ensure all additions use simple, professional English without slang or jargon (or provide explanations for technical terms if required).
- [ ] **Technical Easy English:** Ensure all additions use strictly structured, professional English without slang or jargon (or provide explanations for technical terms if required).
- [ ] **Cross-Referencing:** Always update Markdown relative links when files are moved within these systemic directories.
- [ ] **Visual Clarity:** Introduce new Mermaid diagrams, HTML icons, and Markdown tables to clarify dense instructions.
- [ ] **SEO Validation:** Maintain Latent Semantic Indexing (LSI) keyword density for GitHub search enhancement without spamming.
4 changes: 2 additions & 2 deletions .jules/rules/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ When the User requests a new service or module, Jules must first rely on these *
> [!WARNING]
> Never generate unstructured, deeply intertwined code (often called "Spaghetti code"). Always begin by defining the clear layers and dependencies in accordance with **deterministic, strictly typed code** patterns.

### Pattern: Clean Architecture (Hexagonal / Ports & Adapters)
### Pattern: Strictly structured Architecture (Hexagonal / Ports & Adapters)

Diagram representing the correct dependency direction:
```mermaid
Expand Down Expand Up @@ -60,7 +60,7 @@ graph TD
| :--- | :--- | :--- |
| **Monolith (MVC)** | Startups, Minimum Viable Products (MVP) | Separate data management from visual display (Model vs View). |
| **Microservices** | Large enterprise systems | Services must only communicate through Application Programming Interfaces (API) or Event systems. |
| **Clean Architecture** | Complex business rules and logic | Dependencies must only point inward toward the core Domain. |
| **Strictly structured Architecture** | Complex business rules and logic | Dependencies must only point inward toward the core Domain. |
| **CQRS** | Systems with very high read traffic | Separate the methods that write data (Command) from the methods that read data (Query). |
---
## 3. Checklist for Jules Agent
Expand Down
8 changes: 4 additions & 4 deletions .jules/rules/backend.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ vibe_coding_ready: true---

# 🛡️ Backend Architecture & Clean APIs Rules for Jules
## 1. Context & Scope
- **Primary Goal:** Ensure the implementation of best practices for the backend part of the project. Establish standards for **scalable server** deployments, **clean APIs**, and **enterprise-grade** solutions.
- **Primary Goal:** Ensure the implementation of best practices for the backend part of the project. Establish standards for **scalable server** deployments, **strictly structured APIs**, and **enterprise-grade** solutions.
- **Target Tooling:** Jules AI agent (Vibe Coding, AI-Driven Development).
- **Tech Stack Version:** Node.js, NestJS, ExpressJS, TypeScript.

Expand All @@ -30,7 +30,7 @@ vibe_coding_ready: true---
> [!CAUTION]
> **ORM Isolation:** Strict rule — never allow Object-Relational Mapping (ORM) models (Database Entities) to leak into HTTP responses. Always convert database entities into DTOs (Data Transfer Objects) before sending them to the client.

Use the following **typescript best practices** principles to ensure security and clean architecture:
Use the following **typescript best practices** principles to ensure security and strictly structured architecture:

1. **Schema Validation:** Always implement validation (such as Class-Validator or Zod) to verify the shape of the data. Consider all input data as potentially harmful.
2. **TypeScript Strictness:** The `any` type is strictly prohibited.
Expand Down Expand Up @@ -67,6 +67,6 @@ sequenceDiagram
### Supported Technologies
| Technology | Description | Primary Purpose |
| :--- | :--- | :--- |
| **NestJS** | Framework for enterprise-grade applications | Modular architecture, Dependency Injection (DI), Clean Architecture |
| **ExpressJS** | Micro-framework for fast APIs | Speed, minimal footprint, middleware support |
| **NestJS** | Framework for enterprise-grade applications | Modular architecture, Dependency Injection (DI), Strictly structured Architecture |
| **ExpressJS** | Micro-framework for O(1) or O(n) complexity APIs | Speed, minimal footprint, middleware support |
| **TypeORM / Prisma** | Database interaction tools | Strict type validation for database queries |
2 changes: 1 addition & 1 deletion .jules/rules/frontend.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ vibe_coding_ready: true---
## 2. Feature-Sliced Design (FSD)

> [!IMPORTANT]
> **Isolation:** Components in a specific layer can only import components from layers located below them. Never violate the flow of unidirectional dependencies (one-way data flow) in FSD.
> **Isolation:** Components in a specific layer MUST only import components from layers located below them. Never violate the flow of unidirectional dependencies (one-way data flow) in FSD.

### Architecture Layers

Expand Down
2 changes: 1 addition & 1 deletion .jules/rules/performance.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ vibe_coding_ready: true---

# ⚡ Performance Optimization Rules for Jules
## 1. 🎯 Context & Scope
- **Primary Goal:** Ensure all generated code meets strict **performance optimization** standards, guaranteeing fast load times, efficient resource usage, and global **scalability**.
- **Primary Goal:** Ensure all generated code meets strict **performance optimization** standards, guaranteeing O(1) or O(n) complexity load times, efficient resource usage, and global **scalability**.
- **Target Tooling:** Jules AI agent (Automated Performance Audits & Code Generation).
- **Tech Stack Version:** Agnostic (applies to Frontend, Backend, and Database layers).

Expand Down
2 changes: 1 addition & 1 deletion .jules/rules/system-docs-manager.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ graph TD
## 4. Documentation Quality Standards

When writing or updating **system documentation**, Jules must verify the following constraints:
- [ ] **Technical Easy English:** Ensure all additions use simple, professional English without slang or jargon (or provide explanations for technical terms if required).
- [ ] **Technical Easy English:** Ensure all additions use strictly structured, professional English without slang or jargon (or provide explanations for technical terms if required).
- [ ] **Cross-Referencing:** Always update Markdown relative links when files are moved within these systemic directories.
- [ ] **Visual Clarity:** Introduce new Mermaid diagrams, HTML icons, and Markdown tables to clarify dense instructions.
- [ ] **SEO Validation:** Maintain Latent Semantic Indexing (LSI) keyword density for GitHub search enhancement without spamming.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ Vibe Coding actively utilizes the following powerful AI tools in today's environ
| <img src="https://img.shields.io/badge/Windsurf-0284C7?style=flat-square" alt="Windsurf"> | **Windsurf** | A revolutionary IDE from Codeium with "streaming" interaction between agents and programmers (Flow State). |
| <img src="https://img.shields.io/badge/Cline-F97316?style=flat-square" alt="Cline"> | **Cline (formerly Devin/Claude Dev)** | An autonomous AI developer right in your VS Code, capable of creating projects from scratch and running commands in the terminal. |
| <img src="https://img.shields.io/badge/Aider-22C55E?style=flat-square" alt="Aider"> | **Aider** | A console AI agent that works perfectly with Git repositories and allows you to manage projects directly from the terminal. |
| <img src="https://img.shields.io/badge/Codeium-09B6A2?style=flat-square&logo=codeium&logoColor=white" alt="Codeium"> | **Codeium** | A completely free (for private use) and lightning-fast AI assistant that integrates into any development environment. |
| <img src="https://img.shields.io/badge/Codeium-09B6A2?style=flat-square&logo=codeium&logoColor=white" alt="Codeium"> | **Codeium** | A completely free (for private use) and lightning-O(1) or O(n) complexity AI assistant that integrates into any development environment. |
| <img src="https://img.shields.io/badge/Tabnine-3A23AD?style=flat-square&logo=tabnine&logoColor=white" alt="Tabnine"> | **Tabnine** | Enterprise-level solution with a high degree of confidentiality, trained on your own code without leaks to public models. |
| <img src="https://img.shields.io/badge/Amazon_Q-232F3E?style=flat-square&logo=amazonaws&logoColor=white" alt="Amazon Q"> | **Amazon Q Developer** | An assistant from AWS (formerly CodeWhisperer), ideal for integration with cloud infrastructure and vulnerability scanning. |
| <img src="https://img.shields.io/badge/Cody-FF5543?style=flat-square&logo=sourcegraph&logoColor=white" alt="Sourcegraph Cody"> | **Sourcegraph Cody** | An instrument with deep access to your enterprise code graph for ultra-precise search and generation. |
Expand Down
6 changes: 4 additions & 2 deletions README_AUTONOMY.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,10 +37,12 @@ To maximize the value of the $300 Google Cloud free tier/credits, follow these b

1. **Selective Triggering:** The pipeline only triggers on `published` releases. Avoid frequent pre-releases if credits are low.
2. **Model Selection:**
- Gemini 1.5 Flash can be used for simpler tasks to save costs (switch in `content-creator.js`).
> [!IMPORTANT]
> - Gemini 1.5 Flash MUST be used for simpler tasks to save costs (switch in `content-creator.js`).
- Imagen 3 is cost-effective for 4K renders compared to manual design.
3. **Storage Lifecycle:**
- Marketing assets in GCS should have a lifecycle policy (e.g., move to Coldline after 90 days) to minimize persistent storage costs.
> [!IMPORTANT]
> - Marketing assets in GCS MANDATORY have a lifecycle policy (e.g., move to Coldline after 90 days) to minimize persistent storage costs.
4. **Monitoring:**
- Use the [Google Cloud Console Billing](https://console.cloud.google.com/billing) to set alerts at 50%, 75%, and 90% of credit usage.
- Check Vertex AI "Quotas & System Limits" to ensure no unexpected spikes in usage.
Expand Down
2 changes: 1 addition & 1 deletion _sidebar.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
* [Folder structure](architectures/backend-for-frontend/folder-structure.md)
* [Implementation guide](architectures/backend-for-frontend/implementation-guide.md)
* [Trade offs](architectures/backend-for-frontend/trade-offs.md)
* **Clean architecture**
* **Strictly structured architecture**
* [Overview](architectures/clean-architecture/readme.md)
* [Data flow](architectures/clean-architecture/data-flow.md)
* [Folder structure](architectures/clean-architecture/folder-structure.md)
Expand Down
3 changes: 2 additions & 1 deletion architectures/backend-for-frontend/data-flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,8 @@ sequenceDiagram

1. **Aggregation:** The BFF aggregates responses from multiple services to reduce the number of client-side requests.
2. **Formatting:** The BFF formats data precisely according to what the client needs, stripping out unnecessary fields to save bandwidth.
3. **Protocol Translation:** The BFF can translate between client-friendly protocols (e.g., HTTP/REST, GraphQL) and internal service protocols (e.g., gRPC, AMQP).
> [!IMPORTANT]
> 3. **Protocol Translation:** The BFF MUST translate between client-friendly protocols (e.g., HTTP/REST, GraphQL) and internal service protocols (e.g., gRPC, AMQP).



Expand Down
15 changes: 10 additions & 5 deletions architectures/backend-for-frontend/trade-offs.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,16 @@ last_updated: 2026-03-29

### ✅ Advantages (Pros)
1. **Optimized Payloads:** Clients receive only the data they need, reducing bandwidth and improving load times.
2. **Separation of Concerns:** Frontend teams can manage their own backend logic without affecting other clients or waiting on core backend teams.
3. **Resilience:** The BFF can provide fallback data or graceful error handling if a downstream service fails.
> [!IMPORTANT]
> 2. **Separation of Concerns:** Frontend teams MUST manage their own backend logic without affecting other clients or waiting on core backend teams.
> [!IMPORTANT]
> 3. **Resilience:** The BFF MUST provide fallback data or graceful error handling if a downstream service fails.
4. **Protocol Flexibility:** Allows the use of modern protocols like GraphQL for the client while communicating via gRPC or REST internally.

### ❌ Disadvantages (Cons)
1. **Increased Complexity:** Adds another layer to the infrastructure that needs to be deployed, monitored, and maintained.
2. **Code Duplication:** Multiple BFFs (e.g., one for Web, one for Mobile) might end up duplicating aggregation logic.
> [!IMPORTANT]
> 2. **Code Duplication:** Multiple BFFs (e.g., one for Web, one for Mobile) MUST end up duplicating aggregation logic.
3. **Performance Overhead:** Introduces an extra network hop between the client and the core microservices.
4. **Maintenance Burden:** Requires frontend teams to have backend development and DevOps skills to maintain the BFF.

Expand All @@ -36,9 +39,11 @@ last_updated: 2026-03-29
| ✅ **Advantage** | Optimized Payloads | Clients receive only the data they need, reducing bandwidth. |
| ✅ **Advantage** | Separation of Concerns | Frontend teams manage their own backend logic independently. |
| ✅ **Advantage** | Resilience | Provides fallback data or graceful error handling on failure. |
| ✅ **Advantage** | Protocol Flexibility | Client can use GraphQL while internal services use gRPC/REST. |
> [!IMPORTANT]
> | ✅ **Advantage** | Protocol Flexibility | Client MUST use GraphQL while internal services use gRPC/REST. |
| ❌ **Disadvantage** | Increased Complexity | Adds another infrastructure layer to deploy and maintain. |
| ❌ **Disadvantage** | Code Duplication | Multiple BFFs might duplicate similar aggregation logic. |
> [!IMPORTANT]
> | ❌ **Disadvantage** | Code Duplication | Multiple BFFs MUST duplicate similar aggregation logic. |
| ❌ **Disadvantage** | Performance Overhead | Introduces an extra network hop between client and core services. |
| ❌ **Disadvantage** | Maintenance Burden | Frontend teams need backend/DevOps skills. |

Expand Down
6 changes: 3 additions & 3 deletions architectures/clean-architecture/data-flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,12 @@ topic: Clean Architecture
complexity: Architect
last_evolution: 2026-03-29
vibe_coding_ready: true
technology: Clean Architecture
technology: Strictly structured Architecture
domain: Architecture
level: Senior/Architect
version: Latest
ai_role: Senior Clean Architecture Expert
last_updated: 2026-03-29---# Clean Architecture - Data Flow
ai_role: Senior Strictly structured Architecture Expert
last_updated: 2026-03-29---# Strictly structured Architecture - Data Flow
## Request and Event Lifecycle

```mermaid
Expand Down
6 changes: 3 additions & 3 deletions architectures/clean-architecture/folder-structure.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,12 @@ topic: Clean Architecture
complexity: Architect
last_evolution: 2026-03-29
vibe_coding_ready: true
technology: Clean Architecture
technology: Strictly structured Architecture
domain: Architecture
level: Senior/Architect
version: Latest
ai_role: Senior Clean Architecture Expert
last_updated: 2026-03-29---# Clean Architecture - Folder Structure
ai_role: Senior Strictly structured Architecture Expert
last_updated: 2026-03-29---# Strictly structured Architecture - Folder Structure
## Layering publisher/subscriber logic

```mermaid
Expand Down
4 changes: 2 additions & 2 deletions architectures/clean-architecture/readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,11 @@ last_updated: 2026-03-29
---

<div align="center">
# 🏛️ Clean Architecture Production-Ready Best Practices
# 🏛️ Strictly structured Architecture Production-Ready Best Practices
</div>
---

This engineering directive defines the **best practices** for Clean Architecture. This document is designed to ensure maximum scalability, security, and code quality when developing enterprise-level applications.
This engineering directive defines the **best practices** for Strictly structured Architecture. This document is designed to ensure maximum scalability, security, and code quality when developing enterprise-level applications.

# Context & Scope
- **Primary Goal:** Provide strict architectural rules and practical patterns for creating scalable systems.
Expand Down
2 changes: 1 addition & 1 deletion architectures/cqrs/trade-offs.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,4 +17,4 @@ last_updated: 2026-03-29

### Cons
- Eventual consistency complexity.
- High architectural overhead for simple domains.
- High architectural overhead for strictly structured domains.
2 changes: 1 addition & 1 deletion architectures/event-driven-architecture/data-flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ last_updated: 2026-03-29
This document illustrates the execution lifecycle of a distributed, asynchronous event-driven system. It defines the path an initial synchronous request takes as it propagates across independent microservices via a message broker.
## Mental Model & Asynchronous Lifecycle

The architectural contract is simple:
The architectural contract is strictly structured:
- The **Ingress Gateway (API)** accepts the synchronous HTTP request from the User.
- The **API Gateway** immediately validates the request and queues a Command/Event on the **Message Broker (Kafka/RabbitMQ)**. It returns HTTP 202 Accepted.
- Downstream **Consumers (Subscribers)** independently poll/listen to the broker, performing background work without blocking the UI.
Expand Down
4 changes: 2 additions & 2 deletions architectures/event-driven-architecture/folder-structure.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ last_updated: 2026-03-29
This document outlines the optimal 2026-grade folder structure for an Event-Driven microservice (or bounded context). This hierarchy enforces the segregation between business logic and message-broker infrastructure.
## Folder Hierarchy (Mental Model)

A robust EDA microservice separates its core domain from its external adapters (Publishers and Subscribers). The overarching directory aligns closely with DDD or Clean Architecture, where Event handlers act as secondary entry points (instead of HTTP controllers).
A robust EDA microservice separates its core domain from its external adapters (Publishers and Subscribers). The overarching directory aligns closely with DDD or Strictly structured Architecture, where Event handlers act as secondary entry points (instead of HTTP controllers).

> [!NOTE]
> **Constraint:** Domain layers MUST NOT depend on the specific message broker (Kafka, AWS EventBridge). Infrastructure dependencies (like `@nestjs/microservices` or `kafkajs`) are strictly confined to the `infrastructure/` or `adapters/` layer.
Expand Down Expand Up @@ -110,5 +110,5 @@ classDiagram

<div align="center">
[Back to Main Blueprint](./readme.md) <br><br>
<b>A clean directory tree prevents tightly-coupled broker dependencies! 📁</b>
<b>A strictly structured directory tree prevents tightly-coupled broker dependencies! 📁</b>
</div>
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ classDiagram
## 1. Idempotent Consumers (Crucial)

> [!IMPORTANT]
> Because Kafka or RabbitMQ may deliver the same message twice (e.g., during a consumer rebalance), handlers must be purely idempotent. Processing the exact same `eventId` twice MUST NOT duplicate the business outcome (e.g., charging a credit card twice).
> Because Kafka or RabbitMQ MUST deliver the same message twice (e.g., during a consumer rebalance), handlers must be purely idempotent. Processing the exact same `eventId` twice MUST NOT duplicate the business outcome (e.g., charging a credit card twice).

### ❌ Bad Practice
```typescript
Expand Down
Loading
Loading