Technology Stack

Complete guide to every technology used in Izri and why we chose it

📊 Stack at a Glance

🎨 Frontend Technologies

React Router v7

What it is: Modern full-stack React framework with file-based routing

Why we chose it:

• ✅ Server-side rendering ready
• ✅ File-based routing with excellent DX
• ✅ Built-in data loading patterns
• ✅ Better bundle optimization than competitors
• ✅ Active development and community
• ✅ Smooth migration path from React Router v6

Alternatives considered:

• Next.js: Too opinionated, vendor lock-in concerns
• Remix: React Router v7 is the evolution of Remix
• Create React App: No SSR, deprecated

Key Features:

// Type-safe route definitions
import { type Route } from "./+types/projects"

export async function loader({ params }: Route.LoaderArgs) {
  return { project: await getProject(params.id) }
}

export default function Project({ loaderData }: Route.ComponentProps) {
  return <div>{loaderData.project.name}</div>
}

React 19

What it is: Latest version of the React library

Why we use it:

• ✅ Improved concurrent features
• ✅ Better server components support
• ✅ Enhanced performance
• ✅ New compiler optimizations

Tailwind CSS

What it is: Utility-first CSS framework

Why we chose it:

• ✅ Rapid UI development
• ✅ Consistent design system
• ✅ Small production bundle (purged)
• ✅ No CSS naming conflicts
• ✅ Excellent IntelliSense support

Configuration:

// tailwind.config.js
export default {
  content: ['./app/**/*.{js,jsx,ts,tsx}'],
  theme: {
    extend: {
      colors: {
        // Custom brand colors
      }
    }
  }
}

shadcn/ui

What it is: Copy-paste component library built on Radix UI

Why we chose it:

• ✅ Accessible by default (Radix UI)
• ✅ Fully customizable (you own the code)
• ✅ Consistent with Tailwind
• ✅ No runtime dependency bloat
• ✅ TypeScript support

Components used:

• Button, Input, Select, Dialog
• Table, Card, Badge, Avatar
• DropdownMenu, Tooltip, Toast
• Form components with validation

Vite

What it is: Next-generation frontend build tool

Why we use it:

• ✅ Lightning-fast HMR (<100ms)
• ✅ ESM-based dev server
• ✅ Optimized production builds
• ✅ Built-in TypeScript support
• ✅ Rich plugin ecosystem

⚙️ Backend Technologies

Hono

What it is: Ultra-fast web framework for edge and Node.js

Why we chose it:

• ✅ Fastest Node.js framework (benchmarks)
• ✅ Express-like API (familiar)
• ✅ Excellent TypeScript support
• ✅ Built-in middleware ecosystem
• ✅ Edge runtime compatible
• ✅ Tiny bundle size (~10KB)

Alternatives considered:

• Express: Slower, older architecture
• Fastify: Good but more complex
• Koa: Less active community

Example:

import { Hono } from 'hono'
import { logger } from 'hono/logger'
import { cors } from 'hono/cors'

const app = new Hono()
app.use('*', logger())
app.use('*', cors())

app.get('/health', (c) => c.json({ status: 'ok' }))

tRPC

What it is: End-to-end type-safe RPC framework

Why we chose it:

• ✅ No code generation needed
• ✅ Full type safety from DB to UI
• ✅ Excellent DX with autocomplete
• ✅ Automatic request/response validation
• ✅ Built-in error handling
• ✅ WebSocket support

Alternatives considered:

• REST: No type safety, boilerplate
• GraphQL: Code generation, complexity
• gRPC: Protocol buffers, overkill

Architecture:

// Backend: Define procedures
export const projectRouter = router({
  list: publicProcedure.query(async ({ ctx }) => {
    return ctx.db.select().from(projects)
  }),
  
  create: protectedProcedure
    .input(createProjectSchema)
    .mutation(async ({ ctx, input }) => {
      return ctx.db.insert(projects).values(input)
    })
})

// Frontend: Type-safe calls
const projects = await trpc.projects.list.query()
await trpc.projects.create.mutate({ name: 'New Project' })

Drizzle ORM

What it is: TypeScript ORM that feels like writing SQL

Why we chose it:

• ✅ SQL-like syntax (familiar)
• ✅ Zero runtime overhead
• ✅ Full TypeScript inference
• ✅ No magic, no proxies
• ✅ Excellent migration system
• ✅ Drizzle Studio for visualization

Alternatives considered:

• Prisma: Runtime overhead, code generation
• TypeORM: Complex, heavy
• Kysely: Great but less ecosystem

Example:

// Define schema
import { ulid } from 'ulid';

export const projects = pgTable('projects', {
  id: varchar('id', { length: 191 }).primaryKey(), // ULID stored as varchar
  name: text('name').notNull(),
  organizationId: varchar('organization_id', { length: 191 }).references(() => organizations.id),
  createdAt: timestamp('created_at').defaultNow()
})

// Query with type safety
const result = await db
  .select()
  .from(projects)
  .where(eq(projects.organizationId, orgId))
  .leftJoin(testRuns, eq(testRuns.projectId, projects.id))

// When inserting, generate ULID
const projectId = ulid();
await db.insert(projects).values({
  id: projectId,
  name: 'My Project',
  // ...
})

💾 Data Storage

PostgreSQL 15

What it is: Advanced open-source relational database

Why we chose it:

• ✅ ACID transactions
• ✅ JSONB support (flexible schemas)
• ✅ Excellent indexing options
• ✅ Rich extension ecosystem
• ✅ Proven at scale
• ✅ Strong community support

Features we use:

• JSONB columns for flexible data
• Full-text search
• Partial indexes
• Foreign key constraints
• Transactions

Configuration:

# docker-compose.yml
postgres:
  image: postgres:15-alpine
  environment:
    POSTGRES_DB: izri
    POSTGRES_USER: postgres
    POSTGRES_PASSWORD: postgres
  ports:
    - "5433:5432"
  volumes:
    - postgres_data:/var/lib/postgresql/data

Redis 7

What it is: In-memory data structure store

Why we use it:

• ✅ Ultra-fast caching (<1ms reads)
• ✅ Session storage
• ✅ Rate limiting support
• ✅ Pub/sub messaging
• ✅ Simple to operate

Use cases:

• Session management (Lucia)
• API response caching
• Rate limiting (planned)
• Background job queues (planned)

🤖 AI & Analysis

Python 3.12

Why Python for AI:

• ✅ Best ecosystem for ML/AI
• ✅ LangChain and AI frameworks
• ✅ Tree-sitter for code parsing
• ✅ Excellent async support

FastAPI

What it is: Modern Python web framework

Why we chose it:

• ✅ Async/await support
• ✅ Automatic API documentation
• ✅ Type hints with Pydantic
• ✅ Fast performance
• ✅ Easy to test

Example:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class AnalysisRequest(BaseModel):
    repo_url: str
    branch: str = "main"

@app.post("/analyze")
async def analyze_repo(request: AnalysisRequest):
    # Perform analysis
    return {"status": "success"}

🛠️ Development Tools

pnpm

What it is: Fast, disk space efficient package manager

Why we chose it:

• ✅ 3x faster than npm
• ✅ Efficient disk usage (symlinks)
• ✅ Strict dependency resolution
• ✅ Built-in monorepo support
• ✅ Workspace protocol

Workspace structure:

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

Turbo

What it is: High-performance build system for monorepos

Why we chose it:

• ✅ Intelligent caching
• ✅ Parallel execution
• ✅ Remote caching support
• ✅ Task pipelines
• ✅ Simple configuration

Configuration:

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", "lib/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

TypeScript 5.3+

Why TypeScript:

• ✅ Static type checking
• ✅ Better IDE support
• ✅ Catch errors at compile time
• ✅ Self-documenting code
• ✅ Refactoring confidence

Configuration highlights:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "moduleResolution": "bundler",
    "verbatimModuleSyntax": true
  }
}

🧪 Testing & Quality

Biome

What it is: Fast formatter and linter (Rust-based)

Why we use it:

• ✅ 10x faster than ESLint+Prettier
• ✅ Single tool for format + lint
• ✅ Drop-in replacement
• ✅ Minimal configuration

ESLint (Legacy)

Current state: Transitioning to Biome

Still used for:

• React-specific linting
• Import order enforcement

🐳 Infrastructure & DevOps

Docker & Docker Compose

Why we use it:

• ✅ Consistent development environment
• ✅ Easy service orchestration
• ✅ Production parity
• ✅ Simplified onboarding

Services:

services:
  postgres:
    image: postgres:15-alpine
  redis:
    image: redis:7-alpine
  api:
    build: ./docker/api
  web:
    build: ./docker/web

📊 Comparison with Alternatives

Why Not Next.js?

Why tRPC Over GraphQL?

Why Drizzle Over Prisma?

🎓 Learning Resources

Official Documentation

• React Router
• tRPC
• Drizzle ORM
• Hono
• Tailwind CSS
• shadcn/ui

Internal Guides

• System Overview
• Monorepo Structure
• Data Flow

🔄 Keeping Up to Date

Monitoring Updates

# Check for outdated packages
pnpm outdated

# Update all to latest within version ranges
pnpm update

# Update specific package
pnpm update react-router

Upgrade Strategy

1. Patch versions: Auto-update (security fixes)
2. Minor versions: Review changelog, test, update
3. Major versions: Plan migration, test extensively, update docs

🔗 Next Steps

• Monorepo Structure: Understand code organization
• Design Decisions: Learn why these choices were made
• Frontend Docs: Deep dive into React Router app
• Backend Docs: Deep dive into Hono + tRPC API

Questions about a specific technology? Check the official docs linked above or ask the team.