Developers
Contributing to AIDRAN
AIDRAN is a curated system that tracks how the world talks about AI. It ingests public discourse from seven platforms, enriches it with semantic analysis and signal detection, then publishes AI-generated editorial narratives. This guide covers everything you need to start contributing — from local setup to PR submission.
How the System Works
Understanding the pipeline helps you find where your contribution fits. The system runs four stages, all TypeScript, all deployed as Vercel serverless functions.
Cron workers pull public discourse from 7 platforms (Reddit, Bluesky, X, YouTube, Hacker News, GDELT, The Guardian) via rate-limited API adapters.
Deduplicate, normalize, and generate 512-dim embeddings via Voyage AI. Batch analysis with Claude for sentiment, topics, and entities.
Signal detectors identify anomalies, trend shifts, and narrative opportunities. Semantic clustering, cross-source correlation, gap analysis.
AIDRAN generates editorial narratives from structured intelligence data. Lead stories, beat narratives, dispatches, entity profiles.
Contribution Areas
These are the areas where contributor expertise has the most impact. Each requires different skills and has a different difficulty curve.
Source Adapters
Add ingestion workers for platforms not yet covered. Each adapter normalizes API responses into the shared RawDiscourseRecord schema.
What you'd work on
- Mastodon / ActivityPub federation endpoints
- Stack Overflow / Stack Exchange API
- Substack RSS feeds
- Podcast transcript ingestion
Signal Detectors
Build new signal detection algorithms. Current detectors cover volume, sentiment, platform divergence, entity surge, emotional register, key phrase trends, and cross-topic correlation.
What you'd work on
- Narrative velocity detector (speed of story spread)
- Source authority signals (institutional vs grassroots)
- Temporal pattern detection (day-of-week, seasonal)
Frontend & Visualization
Build data visualization components, improve accessibility, or enhance the editorial reading experience. All components use Tailwind CSS v4 and Framer Motion.
What you'd work on
- Interactive pipeline flow visualization
- Sentiment timeline overlays on beat pages
- Entity relationship network graphs
- Keyboard navigation improvements
Editorial Quality
Improve the AI-generated narrative quality — system prompts, editorial voice, content structure, headline generation, and deduplication thresholds.
What you'd work on
- Beat narrative prompt refinements
- Dispatch tone calibration
- Lead story selection criteria
- Entity name normalization
API & SDK
Extend the REST API with new endpoints, better filtering, pagination improvements, or SDK development.
What you'd work on
- Webhook subscriptions for signal alerts
- GraphQL layer over existing REST endpoints
- Python / JavaScript SDK packages
- Rate limiting per API key tier
Documentation
Improve developer pages, write tutorials, document pipeline internals, or create architecture diagrams.
What you'd work on
- Pipeline stage deep-dive guides
- Signal detector threshold explanations
- Database schema documentation
- Deployment and environment setup guides
Code Conventions
These are non-negotiable. Every PR is reviewed against these standards.
TypeScript everywhere
No Python, no raw JavaScript. Strict mode enabled. All functions typed.
Schema is code
Database schema defined in Drizzle ORM (src/lib/db/schema.ts). No raw SQL migrations unless Drizzle cannot express the change.
Dark-first design
Design and test in dark mode first. Light mode is secondary. Use semantic color tokens (ink, muted, accent, surface, etc.) not raw color values.
Editorial-first layout
Single-column editorial layout. No dashboards, no sidebars, no multi-panel grids. Narrative leads, data supports.
Semantic color tokens
Use the design system tokens: text-ink, text-muted, text-faint, text-accent, bg-surface, bg-raised, border-border. Never use raw Tailwind colors.
Component patterns
Server Components by default. Client Components only when interactivity or browser APIs are needed. Framer Motion for all animations.
Code Style Example
// Server Component by default
export default async function BeatPage({ params }: { params: { slug: string } }) {
const topic = await db.query.topics.findFirst({
where: eq(topics.slug, params.slug),
});
if (!topic) notFound();
return (
<article className="mx-auto max-w-prose">
<h1 className="text-headline text-ink">{topic.name}</h1>
<p className="text-body text-muted">{topic.description}</p>
</article>
);
}
// Client Component only when needed
'use client';
export function SignalChart({ data }: { data: SignalPoint[] }) {
// Interactive visualization that requires browser APIs
}Pull Request Guidelines
Follow these when submitting work. PRs that don't meet these standards will be returned for revision.
Keep PRs focused
One feature or fix per PR. If a refactor is needed to support a feature, submit the refactor as a separate PR first.
Type-check before pushing
Run npx tsc --noEmit and fix all errors. The CI pipeline will reject PRs with type errors.
Test with real data
If you are modifying pipeline stages, test with a real database connection. Mock-based tests have hidden real bugs in the past.
Match the editorial voice
If you are modifying prompts or generated content, read the existing editorial output first. The system has a specific tone — informed, precise, occasionally dry.
Document threshold changes
If you change signal detection thresholds, scoring weights, or cadence limits, document why in the PR description. These are editorial decisions, not just code changes.
PR Checklist
## Checklist
- [ ] `npx tsc --noEmit` passes with no errors
- [ ] Changes are limited to a single feature or fix
- [ ] Tested against a real database (if modifying pipeline code)
- [ ] Semantic color tokens used (no raw Tailwind colors)
- [ ] Server Component by default (Client Component only if interactive)
- [ ] Any threshold or scoring changes are documented in the PR bodyExpress Interest
AIDRAN is invite-only. Fill out this form and we'll review your background. If there's a fit, we'll reach out with repository access and onboarding details.