instantTEA System Documentation
Comprehensive technical guide for the Translational, Ephemeral Assemblages platform.
1. System Overview
instantTEA is an open-source platform for critical policy and governance research. It bridges the gap between policy intent and algorithmic reality by translating complex socio-technical assemblages into provisional, situated snapshots.
Translational
Actively producing knowledge through inscription and enrollment (ANT).
Ephemeral
Capturing fleeting moments of territorialization and deterritorialization.
Critical
Exposing power structures and hidden agencies in governance systems.
2. Architecture
The application is built on a modern Next.js 16 stack, optimized for performance, scalability, and security.
Researcher --> [Auth: Clerk] --> [Next.js App Router]
|
+-------------------+-------------------+
| | |
[Data Layer] [Intelligence] [External]
- Redis (DB) - OpenAI GPT-4 - Stripe
- Vector Search - PDF Parser3. Key Components & Data Flow
3.1 Authentication
Handled via Clerk. Middleware (src/middleware.ts) protects all API and dashboard routes. The app supports a read-only Demo Mode configured via environment variables.
3.2 Data Ingestion & Analysis
- Ingestion: Users upload PDFs or scrape URLs.
- Extraction:
content-extractor.tsparses raw text. - Analysis: Text is sent to
/api/analyzewhere LLM calls are coordinated using specific theoretical lenses. Results are cached in Redis (24h TTL).
3.3 Payments & Credits
Model: Credit-based usage (1 analysis = 1 credit).
Storage: Redis Atomic Counters.
Processing: Stripe Webhooks trigger credit top-ups with signature verification.
4. Security Features
Configured Headers
HSTS, X-Frame-Options, and No-Sniff are strictly enforced in next.config.ts.
Input Validation
Manual checks in API routes and read-only guards for all mutation endpoints ensure data integrity.
5. Configuration
| Variable | Description | Required |
|---|---|---|
| NEXT_PUBLIC_CLERK_KEY | Clerk Auth Public Key | Yes |
| OPENAI_API_KEY | OpenAI API Key | Yes |
| REDIS_URL | Connection string for Redis | Yes |
| STRIPE_SECRET_KEY | Stripe Secret for payments | Yes |