Data Ingestion (Python)
Deterministic pipeline converting canonical JSON sources into sharded distributions and relational SQL exports (PostgreSQL/SQLite).
Hosted API access is disabled on `al-quran-database.vercel.app` for now. Use the repository locally or self-host this project to run the API endpoints documented here.
Architecture
Engineered for precision and scale. The platform utilizes a layered architecture that strictly separates source data, business logic, and transport mechanisms.
Domain Logic (TypeScript)
`lib/data-loader/*` provides high-performance access to Quranic entities with built-in L1 in-memory caching.
Transport (REST & GraphQL)
Stable v1 REST surface and a typed GraphQL query layer with multi-level caching (L1 In-Memory, L2 Redis).
Presentation (Next.js 16)
App Router architecture with React 19. Leveraging Server Components for speed and Framer Motion for interactivity.
Caching Strategy
Level 1
In-Memory
Ultra-low latency cache local to each server instance.
Level 2
Redis
Distributed cache for shared state across horizontally scaled pods.
Monitoring
X-Cache
Full observability via custom headers (hit-memory, hit-redis, miss).
request -> edge validation -> L1 cache -> L2 cache (Redis) -> data loader -> responseQuality Gates
01Deterministic hashing of all generated JSON and SQL artifacts.
02Strict TypeScript compilation and Vitest coverage for core domain logic.
03Playwright E2E smoke tests for API contracts and search UX.