Architecture
Understanding the system design and technical decisions behind Izri
📋 Overview
Izri is built as a modern, scalable monorepo application using TypeScript, React Router, Hono, tRPC, and Python. This section covers the architectural decisions, technology choices, and system design patterns used throughout the project.
🎯 Architectural Goals
The architecture is designed with these principles:
- Type Safety: End-to-end type safety from database to frontend
- Modularity: Clear separation of concerns with workspace packages
- Scalability: Easy to add new features and scale services
- Developer Experience: Fast builds, hot reload, and great tooling
- Maintainability: Clean code structure and comprehensive documentation
- Performance: Optimized for speed with caching and parallel builds
📚 Documentation Pages
System Overview
Essential reading for all developers
High-level architecture covering:
- Overall system design
- Service interactions
- Data flow diagram
- Key components
- Communication patterns
Technology Stack
Complete technology reference
Detailed breakdown of all technologies:
- Frontend technologies (React Router, Tailwind, etc.)
- Backend technologies (Hono, tRPC, Drizzle)
- Infrastructure (Docker, PostgreSQL, Redis)
- Development tools (Turbo, pnpm, TypeScript)
- Why each technology was chosen
Monorepo Structure
Understanding the codebase organization
In-depth explanation of:
- Workspace organization
- Package dependencies
- Build orchestration
- Code sharing patterns
- Import strategies
Data Flow
How data moves through the system
Comprehensive data flow documentation:
- Request/response lifecycle
- Database operations
- State management
- Caching strategies
- Error propagation
Design Decisions
Key architectural and engineering decisions
Historical record of important decisions:
- Why React Router over Next.js
- Why tRPC over REST
- Why Drizzle over Prisma
- Authentication strategy
- Database schema design
- API structure
- Deployment approach
🏗️ Architecture at a Glance
┌─────────────────────────────────────────────────────────────────┐
│ User's Browser │
└────────────────────────────┬────────────────────────────────────┘
│
├─ HTTP/WebSocket
│
┌────────────────────────────▼────────────────────────────────────┐
│ React Router Web App │
│ (apps/web - Port 5173) │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ Routes │ │ Components │ │ tRPC Client │ │
│ │ (Pages) │ │ (UI) │ │ (Type-safe API) │ │
│ └─────────────┘ └──────────────┘ └──────────────────────┘ │
└────────────────────────────┬────────────────────────────────────┘
│
├─ tRPC over HTTP
│
┌────────────────────────────▼────────────────────────────────────┐
│ Hono + tRPC API Server │
│ (apps/api - Port 4000) │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ Routers │ │ Context │ │ Middleware │ │
│ │ (tRPC) │ │ (Auth, DB) │ │ (Logging, Auth) │ │
│ └─────────────┘ └──────────────┘ └──────────────────────┘ │
└────────┬───────────────────────────────────────────┬────────────┘
│ │
├─ Drizzle ORM ├─ HTTP
│ │
┌────────▼──────────────┐ ┌───────────▼─────────────┐
│ PostgreSQL 15 │ │ Python AI Service │
│ (Port 5433/5432) │ │ (Port 8000) │
│ │ │ │
│ ┌─────────────────┐ │ │ ┌──────────────────┐ │
│ │ Tables │ │ │ │ FastAPI │ │
│ │ - users │ │ │ │ - Analysis │ │
│ │ - projects │ │ │ │ - Test Gen │ │
│ │ - test_runs │ │ │ │ - AI Models │ │
│ │ - orgs │ │ │ └──────────────────┘ │
│ └─────────────────┘ │ └─────────────────────────┘
└───────────────────────┘
│
├─ Redis Cache (Port 6379)
│
┌────────▼──────────────┐
│ Redis Server │
│ (Session, Cache) │
└───────────────────────┘
🔧 Core Technologies
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | React Router v7 | Modern React framework with SSR |
| UI Library | shadcn/ui + Tailwind | Beautiful, accessible components |
| API Protocol | tRPC | Type-safe API without code generation |
| HTTP Server | Hono | Fast, lightweight web framework |
| Database ORM | Drizzle ORM | TypeScript-first ORM |
| Database | PostgreSQL 15 | Robust relational database |
| Cache | Redis 7 | In-memory data store |
| AI Service | FastAPI | Python async web framework |
| Package Manager | pnpm | Fast, efficient package manager |
| Build Tool | Turbo | Monorepo build system |
| Type System | TypeScript | Static type checking |
🎨 Design Patterns
1. Monorepo Architecture
- Pattern: pnpm workspaces + Turbo
- Benefits: Code sharing, consistent tooling, atomic changes
- Implementation: See Monorepo Structure
2. Type-Safe API
- Pattern: tRPC with shared types
- Benefits: End-to-end type safety, no code generation needed
- Implementation: See Data Flow
3. Repository Pattern
- Pattern: Database access through Drizzle queries
- Benefits: Testable, maintainable, type-safe database access
- Implementation: See Design Decisions
4. Provider Pattern
- Pattern: React Context for cross-cutting concerns
- Benefits: Clean dependency injection, easy testing
- Implementation: See Frontend docs
5. Middleware Chain
- Pattern: Hono middleware for request processing
- Benefits: Reusable logic, clear separation of concerns
- Implementation: See Backend docs
📊 System Characteristics
Performance
- Build Time: ~20s full build (with Turbo cache: <5s)
- Hot Reload: <100ms for most changes
- API Response: <50ms for cached queries
- Database Queries: <10ms average
- Frontend Bundle: <500KB gzipped
Scalability
- Horizontal: API and AI services can scale independently
- Vertical: Database connection pooling supports high concurrency
- Caching: Redis caching reduces database load
- Build: Turbo caching speeds up CI/CD
Reliability
- Type Safety: Catches errors at compile time
- Database Transactions: ACID compliance
- Error Handling: Comprehensive error boundaries
- Logging: Structured logging with Pino
- Observability: OpenTelemetry support
🔐 Security Architecture
Authentication
- OAuth 2.0 with GitHub (primary)
- Credentials-based fallback
- API token support for programmatic access
- Session management with secure cookies
Data Protection
- PostgreSQL with encrypted connections
- Environment variable management
- Input validation with Zod
- SQL injection protection (parameterized queries)
- XSS protection (React's built-in escaping)
API Security
- CORS configuration
- Rate limiting (planned)
- Request validation
- Authentication middleware
- Authorization checks
🚀 Deployment Architecture
Development
- Docker Compose for local infrastructure
- Hot reload for all services
- Drizzle Studio for database inspection
- Structured logging
Production (Planned)
- Containerized services
- Load balancing
- Database replication
- Redis clustering
- CDN for static assets
- Log aggregation
- Monitoring and alerts
📖 Deep Dive Guides
For New Developers
Start with these in order:
- System Overview - Big picture understanding
- Technology Stack - What we use and why
- Monorepo Structure - Code organization
For Experienced Developers
Focus on these:
- Design Decisions - Why things are the way they are
- Data Flow - How everything connects
- Backend/Frontend specific docs for implementation details
🎓 Learning Path
Start Here: System Overview
↓
Technology Stack (understand the tools)
↓
Monorepo Structure (navigate the code)
↓
Data Flow (understand communication)
↓
Design Decisions (learn the "why")
↓
Implementation Guides (Frontend/Backend docs)
🔗 Related Documentation
- Frontend Architecture: Frontend Documentation
- Backend Architecture: Backend Documentation
- Package Design: Packages Documentation
- Deployment: Deployment Documentation
🤝 Contributing to Architecture
When proposing architectural changes:
- Document the decision in Design Decisions
- Update affected diagrams and documentation
- Discuss in PR with the team
- Consider impact on all packages
- Update this README if needed
Ready to dive deep? Start with System Overview →