> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Antony-Figueroa/my-evershop-app/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Learn about EverShop, a modular Node.js e-commerce framework built with Express, PostgreSQL, and React

## What is EverShop?

EverShop is a modern, modular e-commerce framework built on a powerful technology stack designed for flexibility and scalability. It follows a plugin-based architecture that separates business logic from presentation, making it easy to customize and extend your online store.

<Note>
  This project is built on EverShop **version 2.1.1** with TypeScript support for both backend and frontend development.
</Note>

## Technology Stack

EverShop is built on proven, enterprise-grade technologies:

<CardGroup cols={2}>
  <Card title="Backend" icon="server">
    * **Node.js** - Runtime environment
    * **Express** - Web framework
    * **PostgreSQL** - Database
    * **GraphQL** - API layer
  </Card>

  <Card title="Frontend" icon="palette">
    * **React** - UI components
    * **TypeScript** - Type safety
    * **Tailwind CSS** - Styling
    * **Server-side rendering** - Performance
  </Card>
</CardGroup>

## Architecture Overview

EverShop's architecture is based on two fundamental pillars:

### 1. Extensions (Business Logic)

Extensions encapsulate all custom functionality in isolated, reusable modules:

```typescript theme={null}
extensions/[name]/
├── src/
│   ├── api/              // REST API endpoints
│   ├── pages/            // Page components
│   ├── subscribers/      // Event handlers
│   ├── crons/            // Scheduled jobs
│   ├── graphql/          // GraphQL types & resolvers
│   └── bootstrap.ts      // Extension initialization
├── package.json
└── tsconfig.json
```

### 2. Themes (Visual Presentation)

Themes define the visual appearance and user experience:

```typescript theme={null}
themes/[name]/
├── src/
│   └── pages/            // React components
│       ├── all/          // Global components
│       ├── homepage/     // Homepage components
│       └── account/      // Account pages
├── package.json
└── tsconfig.json
```

## Key Features

<CardGroup cols={2}>
  <Card title="Modular Architecture" icon="puzzle-piece">
    Build features as independent extensions that can be enabled, disabled, or replaced without affecting the core system.
  </Card>

  <Card title="TypeScript First" icon="code">
    Full TypeScript support with strict type checking for both backend logic and React components.
  </Card>

  <Card title="GraphQL API" icon="diagram-project">
    Flexible GraphQL layer for efficient data fetching with type extensions and custom resolvers.
  </Card>

  <Card title="Hot Reload Development" icon="bolt">
    Fast development workflow with hot module replacement for both backend and frontend code.
  </Card>

  <Card title="Component-Based UI" icon="layer-group">
    React components with area-based layouts, allowing precise control over component placement and rendering order.
  </Card>

  <Card title="Event-Driven" icon="broadcast-tower">
    Powerful subscriber system for handling events and creating loosely coupled integrations.
  </Card>
</CardGroup>

## Project Configuration

The current project is configured with:

* **Language**: Spanish (es)
* **Currency**: USD
* **Active Extensions**:
  * `offlinePayments` - Cash on delivery and bank transfer payment methods
  * `productCatalog` - Extended product information for supplements
  * `productReviews` - Customer review system
* **Active Theme**: `anasuplements` - Optimized for supplement e-commerce

## Configuration System

EverShop uses a hierarchical configuration system:

```bash theme={null}
config/
├── default.json          # Base configuration
├── development.json      # Development overrides
└── production.json       # Production overrides
```

Configuration is merged in this priority order:

1. `.env` - Environment variables (secrets, database credentials)
2. `config/default.json` - Base configuration
3. `config/[environment].json` - Environment-specific overrides

<Accordion title="Example: Extension Registration">
  ```json theme={null}
  {
    "system": {
      "extensions": [
        {
          "name": "productCatalog",
          "resolve": "extensions/productCatalog",
          "enabled": true
        }
      ],
      "theme": "anasuplements"
    },
    "shop": {
      "language": "es",
      "currency": "USD"
    }
  }
  ```
</Accordion>

## Data Flow

Understand how requests flow through the system:

```mermaid theme={null}
graph LR
    A[User Request] --> B[Express Router]
    B --> C[Middleware Chain]
    C --> D[API/Page Handler]
    D --> E[GraphQL Query]
    E --> F[Database]
    F --> E
    E --> D
    D --> G[Response]
    C --> H[Subscribers]
    H --> I[Event Processing]
```

<Steps>
  <Step title="Request Routing">
    Express router matches the incoming request to the appropriate handler based on `route.json` configuration.
  </Step>

  <Step title="Middleware Processing">
    Request passes through middleware chain (authentication, validation, body parsing).
  </Step>

  <Step title="GraphQL Data Fetching">
    Page components execute GraphQL queries to fetch required data from the database.
  </Step>

  <Step title="Component Rendering">
    React components render with fetched data, respecting area layout and sort order.
  </Step>

  <Step title="Event Broadcasting">
    Subscribers listen for events and trigger background processing or integrations.
  </Step>
</Steps>

## Core Principles

<Warning>
  **Never Modify Core Files**

  Never edit files in `.evershop/` or `node_modules/`. All customizations must be encapsulated in extensions or themes.
</Warning>

### Extension-Based Development

All custom features should be built as extensions:

* ✅ Create new extensions in `extensions/[name]/`
* ✅ Register extensions in `config/default.json`
* ✅ Use TypeScript for type safety
* ❌ Never modify core EverShop files
* ❌ Never put business logic in themes

### Separation of Concerns

* **Extensions** = Business logic, APIs, data processing
* **Themes** = Visual presentation, styling, user experience

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Get EverShop running locally in minutes
  </Card>

  <Card title="Installation Guide" icon="download" href="/installation">
    Detailed installation and configuration instructions
  </Card>

  <Card title="Development" icon="code" href="/guides/creating-extensions">
    Learn how to build extensions and customize your store
  </Card>

  <Card title="API Reference" icon="book" href="/api/graphql/overview">
    Complete API documentation and examples
  </Card>
</CardGroup>