Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
227 lines (181 loc) · 7.26 KB

ARCHITECTURE.md

File metadata and controls

227 lines (181 loc) · 7.26 KB

SprintIQ Architecture

Overview

SprintIQ is built with a modern, scalable architecture using a Next.js frontend with a Node.js/Express backend, PostgreSQL database, and Clerk authentication.

Architecture Stack

Frontend (Next.js 15)

  • Framework: Next.js 15 with App Router
  • Language: TypeScript
  • Styling: TailwindCSS with custom design system
  • UI Components: Radix UI primitives with custom styling
  • State Management: Zustand for client state, TanStack Query for server state
  • Charts: Recharts for data visualization
  • Authentication: Clerk React components

Backend (Node.js/Express)

  • Framework: Express.js with TypeScript
  • Database: PostgreSQL with Prisma ORM
  • Authentication: Clerk backend SDK
  • Job Queue: BullMQ for background processing
  • Validation: Zod for request validation
  • Logging: Custom logger utility

Database (PostgreSQL + Prisma)

  • Primary Database: PostgreSQL 15+
  • ORM: Prisma for type-safe database access
  • Migrations: Prisma migrate for schema management
  • Schema: See prisma/schema.prisma for complete data model

Authentication (Clerk)

  • Provider: Clerk for user management
  • OAuth: GitHub OAuth integration
  • Middleware: Custom Clerk middleware for API routes
  • Frontend: Clerk React hooks and components

Project Structure

sprintiq/
├── src/                          # Frontend source code
│   ├── app/                      # Next.js app directory
│   │   ├── api/                  # API route handlers
│   │   ├── dashboard/            # Dashboard pages
│   │   ├── sign-in/              # Clerk sign-in pages
│   │   └── ...                   # Other pages
│   ├── components/               # React components
│   │   ├── ui/                   # Base UI components
│   │   ├── dashboard/            # Dashboard-specific components
│   │   ├── auth/                 # Authentication components
│   │   └── layout/               # Layout components
│   ├── lib/                      # Utility libraries
│   │   └── utils.ts              # Common utilities
│   ├── stores/                   # Zustand stores
│   ├── types/                    # TypeScript type definitions
│   └── middleware.ts             # Next.js middleware
├── server/                       # Backend source code
│   ├── routes/                   # Express route handlers
│   ├── middleware/               # Express middleware
│   ├── services/                 # Business logic services
│   ├── utils/                    # Backend utilities
│   └── index.ts                  # Server entry point
├── prisma/                       # Database schema and migrations
│   ├── schema.prisma             # Prisma schema
│   └── migrations/               # Database migrations
└── public/                       # Static assets

Key Components

Authentication Flow

  1. Frontend: Clerk components handle sign-in/sign-up UI
  2. Middleware: Next.js middleware protects routes
  3. Backend: Clerk SDK validates tokens on API routes
  4. Database: User data synced between Clerk and PostgreSQL

API Architecture

  • Frontend APIs: Next.js API routes for client-server communication
  • Backend APIs: Express routes for business logic
  • Database: Prisma ORM for type-safe database operations
  • Validation: Zod schemas for request/response validation

Data Flow

  1. User Action: Frontend component triggers action
  2. API Call: TanStack Query manages API requests
  3. Authentication: Clerk middleware validates requests
  4. Business Logic: Express routes handle business logic
  5. Database: Prisma ORM executes database operations
  6. Response: Data flows back through the stack

Environment Configuration

Required Environment Variables

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_..."
CLERK_SECRET_KEY="sk_..."

# Database
DATABASE_URL="postgresql://user:pass@localhost:5432/sprintiq"

# GitHub Integration (optional)
GITHUB_TOKEN="ghp_..."

# OpenAI (optional)
OPENAI_API_KEY="sk-..."

Development Workflow

1. Database Changes

# 1. Update prisma/schema.prisma
# 2. Generate new migration
npx prisma migrate dev --name descriptive-name

# 3. Generate Prisma client
npx prisma generate

2. API Development

# Backend API routes (Express)
server/routes/*.ts

# Frontend API routes (Next.js)
src/app/api/*/route.ts

3. Frontend Development

# Pages
src/app/*/page.tsx

# Components
src/components/*/

Deployment Architecture

Production Stack

  • Frontend: Vercel or similar Next.js hosting
  • Backend: Railway, Render, or containerized deployment
  • Database: PostgreSQL (Supabase, Railway, or managed service)
  • Authentication: Clerk production environment

Graph Intelligence & RAG

  • Knowledge Graph: Neo4j-backed graph (with in-memory fallback) that stores entities such as commits, pull requests, issues, tasks, and documents
  • Temporal Layer: Automatic HAPPENED_BEFORE edges capture chronological sequences with deltaHours/deltaDays metadata for trend traversal
  • Trend Queries: Graph RAG prompt templates highlight temporal edges so agents can analyze how upstream changes (e.g., PR churn) influence downstream signals (e.g., incident volume)

Environment Setup

  1. Database: Set up PostgreSQL instance
  2. Clerk: Configure production Clerk application
  3. Environment: Set production environment variables
  4. Deployment: Deploy frontend and backend separately

Security Considerations

Authentication

  • Clerk handles password security and OAuth flows
  • JWT tokens validated on every API request
  • Role-based access control (RBAC) implemented

API Security

  • Request validation with Zod schemas
  • Rate limiting on sensitive endpoints
  • CORS configuration for cross-origin requests
  • SQL injection prevention via Prisma ORM

Data Privacy

  • User data encrypted at rest (database level)
  • HTTPS enforced in production
  • Environment variables for sensitive configuration

Monitoring and Logging

Logging

  • Structured logging with custom logger utility
  • Request/response logging on API routes
  • Error tracking and monitoring

Performance

  • Database query optimization with Prisma
  • API response caching where appropriate
  • Frontend performance monitoring

Testing Strategy

Unit Tests

  • Jest for TypeScript/JavaScript testing
  • React Testing Library for component testing
  • Prisma testing with test database

Integration Tests

  • API endpoint testing with Supertest
  • Database integration testing
  • End-to-end testing with Playwright

Development Testing

# Run tests
npm test

# Run with coverage
npm run test:coverage

# E2E tests
npm run test:e2e

Migration Notes

From Firebase

  • ✅ Authentication migrated to Clerk
  • ✅ Database migrated to PostgreSQL/Prisma
  • ✅ API routes updated for new architecture
  • ✅ Frontend updated to use Clerk hooks
  • ✅ All Firebase dependencies removed

Breaking Changes

  • Authentication flow completely changed
  • Database schema restructured
  • API endpoints updated
  • Environment variables changed