Docs /roadmap/improvements

Technical Improvements & Tech Debt

Ongoing improvements, refactoring tasks, and technical debt management for Izri.

📋 Overview

This document tracks technical debt, performance optimizations, code quality improvements, and infrastructure enhancements.

Priority Levels:

  • 🔴 Critical - Security, data loss, severe bugs
  • 🟡 High - Performance, UX, important features
  • 🟢 Medium - Code quality, refactoring
  • 🔵 Low - Nice-to-have, polish

🔴 Critical Priority

Security Hardening

Status: 🚧 In Progress

Issues:

  • API token implementation incomplete (schema ready, no endpoints)
  • Session token exposed in logs (need sanitization)
  • No rate limiting on API endpoints
  • CORS configured for development only
  • Webhook signature verification not implemented

Action Items:

  1. Complete API token CRUD endpoints
  2. Implement request logging sanitization
  3. Add rate limiting middleware (100 req/min per IP)
  4. Update CORS for production domains
  5. Implement webhook signature verification
  6. Add CSRF protection for cookie-based auth
  7. Implement API request size limits

Timeline: Q1 2025

Data Integrity

Status: 📋 Planned

Issues:

  • No database backups configured
  • Missing foreign key cascade behaviors
  • No data validation at database level
  • Missing indexes on frequently queried columns

Action Items:

  1. Set up automated PostgreSQL backups (daily)
  2. Review and fix cascade delete behaviors
  3. Add CHECK constraints for data validation
  4. Create composite indexes for common queries
  5. Implement database migration testing
  6. Add database monitoring and alerts

Timeline: Q1 2025

🟡 High Priority

Performance Optimization

Status: 📋 Planned

Current Issues:

  • No database query optimization
  • N+1 query problems in project list
  • Large payloads for analysis results
  • No pagination on list endpoints
  • No caching layer

Improvements:

Database Optimization:

// Before: N+1 query problem
const projects = await db.select().from(projects)
for (const p of projects) {
  const runs = await db.select().from(testRuns).where(eq(testRuns.projectId, p.id))
  // ...
}

// After: Join with eager loading
const projects = await db
  .select()
  .from(projects)
  .leftJoin(testRuns, eq(projects.id, testRuns.projectId))
  .groupBy(projects.id)

Caching Strategy:

// Redis caching for expensive queries
async function getProject(id: string) {
  const cached = await redis.get(`project:${id}`)
  if (cached) return JSON.parse(cached)
  
  const project = await db.query.projects.findFirst(...)
  await redis.set(`project:${id}`, JSON.stringify(project), 'EX', 300)
  return project
}

Pagination:

// Add pagination to all list endpoints
const { data } = await trpc.projects.getProjects.useQuery({
  page: 1,
  pageSize: 50,
  orderBy: 'updatedAt',
  order: 'desc'
})

Action Items:

  1. Add Redis caching layer
  2. Fix N+1 queries with joins
  3. Implement pagination on all list endpoints
  4. Add database query monitoring (slow query log)
  5. Optimize large JSONB fields (compress analysis data)
  6. Implement CDN for static assets

Timeline: Q1-Q2 2025

Impact: 5-10x faster API responses, reduced database load

Error Handling

Status: 🚧 In Progress

Issues:

  • Inconsistent error messages
  • No centralized error logging
  • Missing error boundaries in frontend
  • Generic error messages exposed to users
  • No request ID tracking

Improvements:

Backend Error Handler:

// Centralized error handler
app.onError((err, c) => {
  const requestId = crypto.randomUUID()
  
  logger.error({
    requestId,
    error: err.message,
    stack: err.stack,
    path: c.req.path,
    method: c.req.method
  })
  
  return c.json({
    error: 'Internal server error',
    message: env.IS_PRODUCTION ? 'An error occurred' : err.message,
    requestId
  }, 500)
})

Frontend Error Boundary:

// Global error boundary
export function ErrorBoundary({ error }: { error: Error }) {
  useEffect(() => {
    Sentry.captureException(error)
  }, [error])
  
  return (
    <div className="error-container">
      <h1>Something went wrong</h1>
      <p>Please try again or contact support</p>
      <Button onClick={() => window.location.reload()}>
        Reload Page
      </Button>
    </div>
  )
}

Action Items:

  1. Implement centralized error logging
  2. Add Sentry integration
  3. Create error boundaries for all routes
  4. Add request ID to all logs
  5. Standardize error response format
  6. Create user-friendly error messages
  7. Add error recovery mechanisms

Timeline: Q1 2025

Testing Infrastructure

Status: 📋 Planned

Issues:

  • Test coverage at ~60%
  • No E2E tests
  • No integration tests for tRPC
  • Missing tests for auth flows
  • No CI testing

Improvements:

Unit Tests:

// Add comprehensive unit tests
describe('projects.createProject', () => {
  it('should create project with valid data', async () => {
    const result = await caller.projects.createProject({
      name: 'Test',
      repository: 'https://github.com/user/repo',
      userEmail: 'user@test.com'
    })
    
    expect(result.project).toHaveProperty('id')
    expect(result.project.name).toBe('Test')
  })
  
  it('should reject duplicate repository', async () => {
    // ... existing project
    
    await expect(
      caller.projects.createProject({ ... })
    ).rejects.toThrow('Project with this repository already exists')
  })
})

E2E Tests:

// Playwright E2E tests
test('complete project creation flow', async ({ page }) => {
  await page.goto('/login')
  await page.click('text=Sign in with GitHub')
  // ... OAuth flow
  
  await page.goto('/projects/new')
  await page.fill('[name="name"]', 'Test Project')
  await page.fill('[name="repository"]', 'https://github.com/user/repo')
  await page.click('button[type="submit"]')
  
  await expect(page).toHaveURL(/\/projects\/proj_/)
})

Action Items:

  1. Increase test coverage to 80%
  2. Add integration tests for all tRPC routers
  3. Implement E2E tests with Playwright
  4. Set up CI testing (GitHub Actions)
  5. Add test database seeding
  6. Implement test fixtures
  7. Add performance testing

Timeline: Q1-Q2 2025

🟢 Medium Priority

Code Quality

Status: 🚧 In Progress

Issues:

  • Inconsistent code style
  • Missing JSDoc comments
  • Large component files (>500 lines)
  • Duplicate code in multiple places
  • Complex functions (>50 lines)

Improvements:

Code Organization:

// Before: Large file with everything
// projects.tsx (800 lines)

// After: Split into smaller files
// components/
//   ProjectCard.tsx
//   ProjectList.tsx
//   CreateProjectForm.tsx
//   ProjectFilters.tsx
// hooks/
//   useProjects.ts
//   useProjectForm.ts
// utils/
//   projectUtils.ts

Extract Utilities:

// Before: Duplicate code
const slug1 = name1.toLowerCase().replace(/\s+/g, '-')
const slug2 = name2.toLowerCase().replace(/\s+/g, '-')

// After: Shared utility
export function slugify(text: string): string {
  return text.toLowerCase()
    .replace(/\s+/g, '-')
    .replace(/[^a-z0-9-]/g, '')
}

Action Items:

  1. Configure ESLint with stricter rules
  2. Add Prettier for consistent formatting
  3. Break down large components (<200 lines each)
  4. Extract duplicate code into utilities
  5. Add JSDoc comments to public functions
  6. Implement import organization rules
  7. Add code complexity linting

Timeline: Ongoing (20% of sprint capacity)

Type Safety

Status: 🚧 In Progress

Issues:

  • Some any types still present
  • Missing Zod validation on some inputs
  • Incomplete tRPC input/output types
  • No runtime type checking in places

Improvements:

Replace any Types:

// Before
const updateData: any = {}
if (input.name) updateData.name = input.name

// After
type UpdateProjectData = Partial<Pick<Project, 'name' | 'description' | 'branch'>>
const updateData: UpdateProjectData = {}
if (input.name) updateData.name = input.name

Add Zod Validation:

// Before: No validation
const updateData = { name: input.name }

// After: Zod schema
const updateProjectSchema = z.object({
  name: z.string().min(1).max(100),
  description: z.string().max(500).optional(),
  branch: z.string().regex(/^[a-zA-Z0-9_/-]+$/).optional()
})

Action Items:

  1. Remove all any types
  2. Add Zod validation to all inputs
  3. Use strict TypeScript config
  4. Add type guards for runtime checks
  5. Implement branded types for IDs
  6. Add exhaustive type checking
  7. Use const assertions where appropriate

Timeline: Q1-Q2 2025

Developer Experience

Status: 📋 Planned

Issues:

  • Slow development builds (Vite)
  • No hot reload for backend
  • Missing dev tools
  • Inconsistent environment setup
  • No debug logging levels

Improvements:

Development Tools:

// Add debug logging
import debug from 'debug'

const log = debug('izri:projects')
log('Creating project: %s', input.name)

// Enable with: DEBUG=izri:* pnpm dev

Better Error Messages:

// Before
throw new Error('Failed')

// After
throw new Error(
  `Failed to create project: ${error.message}\n` +
  `Repository: ${input.repository}\n` +
  `User: ${input.userEmail}`
)

Action Items:

  1. Add development debugging tools
  2. Implement hot reload for backend (tsx watch)
  3. Add request/response logging in dev
  4. Create development seed data script
  5. Add Storybook for component development
  6. Improve error messages with context
  7. Add performance profiling tools

Timeline: Q2 2025

Documentation

Status: ✅ Complete (this documentation)

Improvements Needed:

  • Keep documentation up to date
  • Add inline code comments
  • Create video tutorials
  • Add troubleshooting guides
  • Improve API examples

Action Items:

  1. Review docs quarterly
  2. Add comments to complex code
  3. Create getting started video
  4. Build troubleshooting FAQ
  5. Add more API usage examples
  6. Create architecture diagrams
  7. Document deployment process

Timeline: Ongoing

🔵 Low Priority

UI/UX Polish

Status: 📋 Planned

Improvements:

  • Dark mode support
  • Improved loading states
  • Better empty states
  • Skeleton loaders
  • Animations and transitions
  • Keyboard shortcuts
  • Improved mobile UI

Timeline: Q2-Q3 2025

Accessibility

Status: 📋 Planned

Issues:

  • Missing ARIA labels
  • Keyboard navigation incomplete
  • Color contrast issues
  • Screen reader support needs testing
  • Focus management needs improvement

Action Items:

  1. Audit with axe DevTools
  2. Add ARIA labels to interactive elements
  3. Improve keyboard navigation
  4. Fix color contrast issues
  5. Test with screen readers
  6. Add skip links
  7. Implement focus trap for modals

Timeline: Q2 2025

Internationalization

Status: 💡 Future

Improvements:

  • Multi-language support
  • Date/time localization
  • Number formatting
  • Currency support
  • RTL language support

Timeline: Q3 2025+

📊 Technical Debt Metrics

Current State

Estimated Technical Debt: 3-4 weeks

Debt Ratio: ~15% of codebase

Priority Breakdown:

  • 🔴 Critical: 1 week
  • 🟡 High: 2 weeks
  • 🟢 Medium: 3 weeks
  • 🔵 Low: 2 weeks

Debt Management Strategy

Allocation:

  • 20% of each sprint for tech debt
  • Quarterly refactoring sprints
  • No new features with >15% debt ratio

Tracking:

  • Label PRs as tech-debt
  • Monthly tech debt review
  • Track debt in project board

Prevention:

  • Code review requirements
  • Automated testing
  • Documentation requirements
  • Architecture decision records

🔄 Refactoring Projects

1. Authentication Refactor

Priority: 🟢 Medium

Scope: Consolidate auth logic

Benefits:

  • Easier to maintain
  • Better type safety
  • Clearer error handling

Estimated Effort: 1 week

Timeline: Q1 2025

2. Database Layer Refactor

Priority: 🟡 High

Scope: Add repository pattern

Benefits:

  • Better testability
  • Easier to mock
  • Clearer separation of concerns

Estimated Effort: 2 weeks

Timeline: Q2 2025

3. Component Library

Priority: 🔵 Low

Scope: Extract reusable components

Benefits:

  • Consistent UI
  • Faster development
  • Better documentation

Estimated Effort: 2 weeks

Timeline: Q2 2025

🛠️ Infrastructure Improvements

Monitoring & Observability

Status: 📋 Planned

Improvements:

  • Application Performance Monitoring (APM)
  • Error tracking (Sentry)
  • Log aggregation (Datadog, ELK)
  • Database monitoring
  • Uptime monitoring
  • Cost monitoring

Tools:

  • OpenTelemetry for tracing
  • Prometheus for metrics
  • Grafana for dashboards
  • Sentry for errors
  • Pino for structured logging

Timeline: Q1-Q2 2025

CI/CD Pipeline

Status: 📋 Planned

Improvements:

  • Automated testing on PR
  • Deployment preview environments
  • Automated security scanning
  • Dependency vulnerability checking
  • Performance regression testing
  • Automated releases

Timeline: Q1 2025

Database Performance

Status: 📋 Planned

Improvements:

  • Connection pooling optimization
  • Query performance monitoring
  • Index optimization
  • Partitioning for large tables
  • Read replicas
  • Caching layer (Redis)

Timeline: Q2 2025

📝 Decision Log

Architecture Decisions

ADR-001: Use tRPC instead of REST

  • ✅ Decided: Yes
  • Rationale: Type safety, automatic client generation
  • Trade-off: Less familiar to some developers

ADR-002: Use Drizzle ORM instead of Prisma

  • ✅ Decided: Yes
  • Rationale: Better TypeScript support, SQL-like syntax
  • Trade-off: Smaller community

ADR-003: Use Better Auth instead of NextAuth

  • ✅ Decided: Yes
  • Rationale: Better Hono integration, simpler
  • Trade-off: Less mature ecosystem

ADR-004: Use React Router v7 instead of Next.js

  • ✅ Decided: Yes
  • Rationale: More control, Vite optimization
  • Trade-off: No built-in SSR

🔗 Related Documentation

Reading this with an agent? /docs/roadmap/improvements.md serves the raw markdown.

All docs