> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trendteller.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Key Concepts

> Core concepts and principles behind Trendteller's architecture

## Overview

Understanding these key concepts will help you work effectively with Trendteller's platform and make the most of its capabilities.

## Medallion Architecture

Trendteller implements a Medallion Architecture for data processing, organizing data into three distinct layers:

<Steps>
  <Step title="Bronze Layer (Raw Data)">
    **Purpose**: Store raw, unprocessed data exactly as received from source systems.

    * Data is ingested from Airbyte connectors
    * Maintains original source format and structure
    * Provides full audit trail and data lineage
    * No transformations applied

    **Example**: Raw order data from Bling API with all original fields
  </Step>

  <Step title="Silver Layer (Standardized)">
    **Purpose**: Clean, standardize, and deduplicate data across sources.

    * Applies data quality rules and validations
    * Standardizes data types and formats
    * Deduplicates records across brands
    * Adds business keys and metadata

    **Example**: Orders from all 11 brands in a unified schema
  </Step>

  <Step title="Gold Layer (Analytics-Ready)">
    **Purpose**: Create business-ready data models optimized for analytics.

    * Aggregated metrics and KPIs
    * Pre-joined dimension tables
    * Optimized for query performance
    * Business logic applied

    **Example**: Daily sales metrics by brand, category, and channel
  </Step>
</Steps>

<Tip>
  The Medallion Architecture enables both flexibility (access to raw data) and performance (optimized analytics tables).
</Tip>

## Multi-Brand Consolidation

### Brand Aggregation

Trendteller consolidates data from **11 different brands** across **9 e-commerce platforms** into a unified analytics system.

<AccordionGroup>
  <Accordion title="Supported E-commerce Platforms">
    * **Bling** - Brazilian ERP and e-commerce platform
    * **VNDA** - Fashion retail platform
    * **Shoppub** - Marketplace integration
    * **Tiny** - ERP and inventory management
    * **Microvix** - Retail management system
    * **Braavo** - E-commerce platform
    * **JetERP** - Enterprise resource planning
    * **Google Shopping** - Product feed integration
    * **Totvs Moda** - Fashion industry ERP
  </Accordion>

  <Accordion title="Data Consolidation Strategy">
    Each brand's data is:

    1. Extracted via custom Airbyte connectors
    2. Loaded into Bronze layer with brand identifier
    3. Standardized in Silver layer using common schema
    4. Aggregated in Gold layer for cross-brand analytics

    This enables:

    * Cross-brand performance comparisons
    * Consolidated inventory management
    * Unified customer analytics
    * Portfolio-wide forecasting
  </Accordion>
</AccordionGroup>

### Brand Isolation vs. Consolidation

<Tabs>
  <Tab title="Isolated Views">
    * Each brand's data remains separately accessible
    * Brand-specific dashboards and reports
    * Individual brand performance tracking
    * Maintains data privacy between brands
  </Tab>

  <Tab title="Consolidated Views">
    * Portfolio-wide analytics and insights
    * Cross-brand trend identification
    * Aggregate sales and inventory metrics
    * Unified forecasting models
  </Tab>
</Tabs>

## Data Integration Patterns

### Source-to-Warehouse Pattern

```
Source System → Airbyte Connector → BigQuery (Bronze) → Dataform (Silver/Gold)
```

**Key Principles**:

* **Full Refresh**: Some sources perform complete data refresh
* **Incremental Sync**: Most sources use incremental updates based on modification timestamp
* **Change Data Capture**: Tracks changes at the source level
* **Error Handling**: Failed syncs are logged and can be retried

### API-First Architecture

Trendteller exposes all data through a GraphQL API powered by Hasura V2:

<CardGroup cols={2}>
  <Card title="GraphQL Benefits" icon="diagram-project">
    * Type-safe queries
    * Flexible data fetching
    * Real-time subscriptions
    * Automatic schema generation
  </Card>

  <Card title="Hasura Features" icon="bolt">
    * BigQuery federation
    * PostgreSQL integration
    * Role-based access control
    * Performance optimization
  </Card>
</CardGroup>

## AI-Powered Analytics

### Insights Generation

Trendteller uses AI models to generate actionable insights:

<AccordionGroup>
  <Accordion title="Forecasting" icon="chart-line">
    * Sales forecasting using historical trends
    * Inventory optimization predictions
    * Demand forecasting by product category
    * Seasonality detection and modeling

    **Models Used**: OpenAI GPT-4, Google Gemini AI
  </Accordion>

  <Accordion title="Trend Detection" icon="magnifying-glass-chart">
    * Identifies emerging product trends
    * Detects anomalies in sales patterns
    * Analyzes customer behavior shifts
    * Market trend correlation
  </Accordion>

  <Accordion title="Automated Reporting" icon="file-chart-column">
    * Daily/weekly automated insights
    * Performance summaries by brand
    * Exception reporting (low stock, unusual patterns)
    * Executive dashboards with AI commentary
  </Accordion>
</AccordionGroup>

### Web Crawling

Kestra scripts use Puppeteer for competitive intelligence:

* Competitor pricing monitoring
* Market availability tracking
* Product catalog comparison
* Review and sentiment analysis

## Type-Safe Development

### Frontend Type Safety

The platform frontend uses **Genql** for type-safe GraphQL queries:

```typescript theme={null}
import { createClient } from '@/generated/genql'

const client = createClient()

// Fully typed query
const orders = await client.query({
  orders: {
    id: true,
    total: true,
    customer: {
      name: true,
      email: true
    }
  }
})
```

<Tip>
  Type safety prevents runtime errors and provides excellent IDE autocomplete support.
</Tip>

### Backend Type Safety

Airbyte connectors are built with TypeScript:

* Compile-time type checking
* IDE autocomplete for API schemas
* Reduced runtime errors
* Better maintainability

## Authentication & Authorization

### Auth0 Integration

<Steps>
  <Step title="User Authentication">
    Users authenticate via Auth0 using username/password or social logins.
  </Step>

  <Step title="Token Generation">
    Auth0 issues JWT tokens with user claims and roles.
  </Step>

  <Step title="API Authorization">
    Hasura validates JWT tokens and enforces role-based access control.
  </Step>

  <Step title="Frontend Session">
    Nuxt Auth manages session state and token refresh.
  </Step>
</Steps>

### Role-Based Access

* **Admin**: Full access to all brands and data
* **Brand Manager**: Access to specific brand(s) data
* **Analyst**: Read-only access to analytics
* **API User**: Programmatic API access

## Data Quality & Validation

### Quality Checks

Dataform implements multiple data quality layers:

<CardGroup cols={2}>
  <Card title="Schema Validation" icon="check-circle">
    * Required fields enforcement
    * Data type validation
    * Format standardization
    * Referential integrity
  </Card>

  <Card title="Business Rules" icon="scale-balanced">
    * Logical value constraints
    * Cross-field validations
    * Deduplication logic
    * Historical consistency checks
  </Card>
</CardGroup>

### Monitoring & Alerting

* Data freshness monitoring
* Pipeline failure alerts
* Data quality score tracking
* Anomaly detection

## Next Steps

<CardGroup cols={2}>
  <Card title="System Overview" icon="sitemap" href="/system-overview">
    Review the complete system architecture
  </Card>

  <Card title="Components" icon="cube" href="/components/platform-frontend">
    Explore individual system components
  </Card>

  <Card title="Architecture" icon="building" href="/architecture/overview">
    Deep dive into architectural decisions
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Start building with the API
  </Card>
</CardGroup>