Introduction

Orange is an Amazon seller analytics backend that ingests, transforms, and stores seller reports for downstream analysis. These docs provide a technical overview of the platform's data model, setup instructions, and operational guides.

Quick Links

• Local Development Setup - Get started (Docker, DevContainer, or Native)
• Reporting Structure - Understanding Row vs Range models
• Database Tables - Complete schema reference
• Observability - OpenTelemetry and SigNoz monitoring

What is Orange?

Orange provides a schema-driven data ingestion system for Amazon seller data:

• 14 Report Types - Sponsored Products, Business Reports, Search Query Performance
• Flexible Temporal Models - Daily snapshots (Row Model) or period aggregates (Range Model)
• Automatic Deduplication - Smart upserts based on uniqueness keys
• Complete Audit Trail - Track every change, enable upload reversal
• RESTful API - FastAPI-powered endpoints with JWT authentication

Key Features

📊 Report Processing

• CSV upload validation with schema enforcement
• Field transformations (percentages, currency, numbers)
• Intersection checks to prevent misattributed data
• Upload tracking and reversal capabilities

🗄️ Data Management

• Parent-child ASIN relationships
• Brand management with fuzzy matching
• Seller-brand mapping
• Review lifecycle tracking

🔍 Analysis Ready

• Normalized data model optimized for analytics
• Period-based querying (daily, weekly, monthly, quarterly)
• Filtering and pagination on all endpoints
• CSV export with custom column selection

🚀 Production Ready

• Docker containerization
• Celery for async tasks
• OpenTelemetry observability
• Azure Blob Storage integration
• Comprehensive test coverage

Getting Started

1. Set up your local environment using Docker Compose
2. Read Reporting Structure to understand data models
3. Review Database Tables for schema details

Architecture

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│  CSV Upload │ ───► │  Validation  │ ───► │  Transform  │
│  (via API)  │      │  (Schema)    │      │  & Upsert   │
└─────────────┘      └──────────────┘      └─────────────┘
                                                    │
                                                    ▼
┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│  Analytics  │ ◄─── │  PostgreSQL  │ ◄─── │ Audit Trail │
│   Queries   │      │   Database   │      │  (Changes)  │
└─────────────┘      └──────────────┘      └─────────────┘

Support

• GitHub Issues: equalcollective/santra-be
• OpenSpec Docs: See /openspec/project.md for comprehensive project documentation.