Skip to main content

System Architecture Deep Dive

Core Architecture Principles​

1. Microservices Architecture​

  • Frontend: Next.js 15 with App Router (SSR/SSG)
  • Backend: API Routes + External Services
  • AI Services: Separate Python services (LangGraph, Document Processing)
  • Database: Supabase (PostgreSQL) with RLS

2. Technology Stack Details​

LayerTechnologyVersionPurpose
FrontendNext.js15.2.5React framework with App Router
React19.1.0UI library
TypeScript5.5+Type safety
ZustandLatestState management
shadcn/uiLatestComponent library
BackendNode.js20.12+Runtime
SupabaseLatestDatabase & Auth
RedisLatestCaching layer
SQLiteLatestLocal caching
AI/MLOpenAILatestGPT models
AnthropicLatestClaude models
LangChainLatestAI orchestration
Python3.11+AI services
InfrastructureAzure-Cloud platform
KubernetesLatestContainer orchestration
DockerLatestContainerization

Data Flow Architecture​

Database Architecture​

Supabase Schema Overview​

  • Users & Authentication: Managed by Supabase Auth
  • Organizations: Multi-tenant support
  • Files & Documents: File management with embeddings
  • Opportunities: Pipeline management
  • Chats & Messages: Conversation history
  • Knowledge Base: Categorized content

Key Database Features​

  1. Row Level Security (RLS): All tables have RLS policies
  2. Embeddings: Vector storage for semantic search
  3. Materialized Views: Performance optimization
  4. Triggers: Automated data maintenance

Deployment Architecture​

Environments​

  1. Development: Local development
  2. QA Commercial: qa-commercial.awardedai.com
  3. QA Government: qa-government.awardedai.com
  4. Production Commercial: *.awardedai.com
  5. Production Government: *.awardedai.com (Azure Gov)
  6. Sandbox: Testing environment

CI/CD Pipeline​

GitHub Push → GitHub Actions → Docker Build → Azure Container Registry → AKS Deployment

Container Services​

  • web: Main Next.js application
  • ai: Python AI services
  • nest: Shared services API
  • doc-pipeline: Document processing
  • workflows: LangGraph workflows
  • agenting: Agent services

Future Architecture: LangGraph Platform​

The strategic migration to LangGraph Platform will consolidate our AI services:

Benefits:

  • Unified Development: One way to build AI features
  • Built-in Evaluations: Move from tests to observations
  • Native Observability: LangSmith integration out of the box
  • Improved DevEx: Faster development cycles

Security Architecture​

Authentication & Authorization​

  • Supabase Auth: Primary authentication
  • NextAuth: Session management
  • RLS Policies: Database-level security
  • API Keys: Service-to-service auth

Data Security​

  • Encryption at Rest: Azure Storage
  • Encryption in Transit: HTTPS/TLS
  • Secrets Management: 1Password + Azure Key Vault
  • RBAC: Role-based access control

Performance Architecture​

Caching Strategy​

  1. SQLite: Primary cache (always available)
  2. Redis: Secondary cache (distributed)
  3. In-Memory: Fallback cache
  4. CDN: Static asset caching

Optimization Techniques​

  • Code Splitting: Dynamic imports
  • Image Optimization: Next.js Image component
  • API Caching: 30-minute default TTL
  • Database Indexes: HNSW for vector search

Monitoring & Observability​

Tools & Services​

  • Sentry: Error tracking
  • PostHog: Analytics & feature flags
  • OpenTelemetry: Distributed tracing
  • Custom Logging: Structured JSON logs

Key Metrics​

  • API response times
  • Error rates
  • Cache hit rates
  • AI model performance
  • User engagement

Scalability Considerations​

Current Scale​

  • Users: ~1000+ active users
  • Data: 1.38M lines of code
  • Files: Millions of documents
  • API Calls: Thousands per minute

Scaling Strategy​

  1. Horizontal Scaling: Kubernetes pods
  2. Database Sharding: Future consideration
  3. CDN Expansion: Global distribution
  4. AI Model Optimization: Response caching

Technical Debt Areas​

Identified Issues​

  1. Test Coverage: Currently at 38.48%
  2. TODO/FIXME: 313 files with markers
  3. Type Safety: Some any types remain
  4. Documentation: Needs expansion
  5. Performance: Cache optimization needed
  1. Implement comprehensive testing strategy
  2. Address technical debt systematically
  3. Improve type safety across codebase
  4. Enhance documentation coverage
  5. Optimize caching mechanisms