This document follows the C4 Model (Context, Containers, Components, Code) standard for documenting the VTEX Rewriter architecture.

⚙️ Technical Details: For detailed technical diagrams, flows, and troubleshooting information, see Complete Architecture Documentation.

The C4 model provides a hierarchical set of software architecture diagrams for context, containers, components, and code.

• Level 1: System Context - Shows how the software system fits into the world
• Level 2: Container - Shows the high-level shape of the architecture
• Level 3: Component - Shows how a container is made up of components
• Level 4: Code - Shows how a component is implemented

---

Shows how the VTEX Rewriter fits into the overall VTEX ecosystem.

Key Relationships:

• Customers browse the storefront and trigger route resolution
• Store Admins manage routes and redirects through Admin UI
• VTEX Router forwards requests to Rewriter based on routing rules
• Rewriter processes URLs, applies redirects, and proxies to Render Server
• VBase stores all route and redirect configurations
• Catalog API provides product and category data for route resolution

---

Shows the high-level technology choices and how containers communicate.

Technology Stack:

• Node.js - Runtime environment
• TypeScript - Primary language
• GraphQL - API layer
• Express.js - HTTP server framework
• VBase - Document storage
• LRU Cache - In-memory caching

---

Shows how the Node.js application is structured internally.

Key Components:

• HTTP Handlers - Entry points for different request types
• GraphQL API - Admin interface for route management
• Middleware Pipeline - Sequential request processing
• Route Resolvers - Business logic for different route types
• Resource Layer - Data abstraction and validation
• API Clients - External service integrations
• LRU Caches - Performance optimization

---

Shows the internal structure of the critical Route Identifier component.

Key Classes and Responsibilities:

1. RouteIdentifier - Main orchestrator

   
   

   _10

   class RouteIdentifier {

   _10

   async identify(ctx: Context): Promise<Route | null>

   _10

   private async findRedirect(locator: RouteLocator): Promise<Redirect | null>

   _10

   private async findInternal(locator: RouteLocator): Promise<Internal | null>

   _10

   }

   
   

2. RedirectStrategy - Redirect route resolution

   
   

   _10

   class RedirectStrategy implements RouteStrategy {

   _10

   async resolve(locator: RouteLocator): Promise<Redirect | null>

   _10

   private async searchWithQueryString(locator: RouteLocator): Promise<Redirect | null>

   _10

   private async searchWithoutQueryString(locator: RouteLocator): Promise<Redirect | null>

   _10

   }

   
   

3. RouteValidator - Route validation logic

   
   

   _10

   class RouteValidator {

   _10

   validateRedirect(redirect: Redirect): ValidationResult

   _10

   validateInternal(internal: Internal): ValidationResult

   _10

   checkExpiration(route: Route): boolean

   _10

   }

   
   

---

This C4 model provides a comprehensive view of the VTEX Rewriter architecture at all necessary levels of detail.