Skip to main content

SDD-001: Technology Stack - Software Design Document

Version: 1.0.0 Status: Approved Last Updated: 2025-12-28 Author: Hal Casteel

1. Executive Summary​

This Software Design Document defines the complete technology stack for the CODITECT Document Management System. The stack is optimized for:

  • High-performance semantic search with vector embeddings
  • Multi-tenant SaaS architecture with complete isolation
  • Async-first design for I/O-bound operations
  • Enterprise-grade reliability with 99.9% uptime target
  • Scalability from 10 to 10,000+ concurrent users

Context​

The current situation requires a decision because:

  • Requirement 1
  • Constraint 2
  • Need 3

Status​

Accepted | YYYY-MM-DD

2. Architecture Overview​

┌─────────────────────────────────────────────────────────────────┐
│                        CLIENT LAYER                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │ React 18.2+  │  │   Mobile     │  │   Third-Party APIs   │   │
│  │ TypeScript   │  │   (Future)   │  │   (REST/GraphQL)     │   │
│  └──────────────┘  └──────────────┘  └──────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      API GATEWAY LAYER                           │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                   Cloud Run / GKE                         │   │
│  │  • Load Balancing        • SSL Termination                │   │
│  │  • Rate Limiting         • Request Routing                │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    APPLICATION LAYER                             │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │                    FastAPI (Python 3.11+)                   │ │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐   │ │
│  │  │   Routes    │ │  Services   │ │     Background      │   │ │
│  │  │   (REST)    │ │  (Business) │ │   (Celery Tasks)    │   │ │
│  │  └─────────────┘ └─────────────┘ └─────────────────────┘   │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                       DATA LAYER                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │ PostgreSQL   │  │    Redis     │  │   Cloud Storage      │   │
│  │ + pgvector   │  │   (Cache)    │  │   (Documents)        │   │
│  │ + TimescaleDB│  │              │  │                      │   │
│  └──────────────┘  └──────────────┘  └──────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    EXTERNAL SERVICES                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │   OpenAI     │  │  Anthropic   │  │      Stripe          │   │
│  │ (Embeddings) │  │  (Voyage)    │  │    (Billing)         │   │
│  └──────────────┘  └──────────────┘  └──────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

3. Technology Stack Details​

3.1 Backend Layer​

Primary Framework: FastAPI​

AttributeValue
FrameworkFastAPI 0.109+
Python Version3.11+ (required for performance)
ASGI ServerUvicorn with Gunicorn workers
ValidationPydantic V2
ADR ReferenceADR-024: FastAPI Web Framework

Selection Rationale:

  • Native async/await for non-blocking I/O
  • Automatic OpenAPI documentation
  • Pydantic integration for type-safe validation
  • High performance (15,000+ req/s)
  • Production-proven at Netflix, Uber, Microsoft

Key Dependencies:

fastapi>=0.109.0
uvicorn[standard]>=0.27.0
pydantic>=2.5.0
python-jose[cryptography]>=3.3.0
passlib[bcrypt]>=1.7.4
python-multipart>=0.0.6

ORM & Database Access​

ComponentTechnologyPurpose
ORMSQLAlchemy 2.0+Async ORM with type hints
DriverasyncpgNative async PostgreSQL driver
MigrationsAlembicDatabase schema versioning
VectorpgvectorVector similarity operations

Key Dependencies:

sqlalchemy>=2.0.25
asyncpg>=0.29.0
alembic>=1.13.0
pgvector>=0.2.4

Background Processing​

ComponentTechnologyPurpose
Task QueueCelery 5.3+Distributed task processing
BrokerRedisMessage broker
Result BackendRedisTask result storage
SchedulerCelery BeatPeriodic tasks

Key Dependencies:

celery>=5.3.0
redis>=5.0.0
flower>=2.0.0  # Monitoring

3.2 Database Layer​

PostgreSQL 15+​

FeatureConfiguration
VersionPostgreSQL 15
Extensionspgvector, TimescaleDB, uuid-ossp
Connection PoolingPgBouncer (production)
ReplicationStreaming (HA environments)

pgvector Configuration:

-- Vector similarity search
CREATE EXTENSION vector;

-- Embedding dimensions
-- OpenAI text-embedding-3-small: 1536
-- OpenAI text-embedding-3-large: 3072
-- Voyage-3: 1024

CREATE INDEX idx_chunk_embedding_ivfflat
ON chunk USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);

TimescaleDB Configuration:

-- Time-series metrics
CREATE EXTENSION timescaledb CASCADE;

-- Hypertables for metrics
SELECT create_hypertable('document_metric', 'recorded_at');
SELECT create_hypertable('search_metric', 'recorded_at');

Redis 7.0+​

Use CaseConfiguration
CachingTTL-based document cache
SessionsJWT blacklist, user sessions
Rate LimitingSliding window counters
Distributed LocksRedlock algorithm
Celery BrokerTask queue messaging

Memory Configuration:

  • Development: 1 GB
  • Staging: 2 GB
  • Production: 5+ GB (HA)

3.3 Frontend Layer​

React 18.2+​

ComponentTechnology
FrameworkReact 18.2+
LanguageTypeScript 5.3+ (strict mode)
State ManagementTanStack Query (server state) + Zustand (client state)
RoutingReact Router 6+
UI ComponentsRadix UI + Tailwind CSS
Build ToolVite
TestingVitest + React Testing Library

Key Dependencies:

{
  "react": "^18.2.0",
  "react-dom": "^18.2.0",
  "typescript": "^5.3.0",
  "@tanstack/react-query": "^5.0.0",
  "zustand": "^4.4.0",
  "react-router-dom": "^6.20.0",
  "@radix-ui/react-*": "latest",
  "tailwindcss": "^3.4.0"
}

3.4 Infrastructure Layer​

Google Cloud Platform (GCP)​

ServicePurposeConfiguration
Cloud RunAPI deploymentAuto-scaling, 0-100 instances
Cloud SQLPostgreSQL hostingPrivate IP, SSL required
MemorystoreRedis hosting1-5 GB, HA optional
Cloud StorageDocument storageRegional, versioned
Secret ManagerCredentialsAutomatic rotation
Cloud BuildCI/CDTriggered on push
Cloud MonitoringObservabilityPrometheus + Grafana

Infrastructure as Code​

ToolPurpose
Terraform/OpenTofuInfrastructure provisioning
Kubernetes (GKE)Container orchestration (production)
HelmKubernetes package management

3.5 External Integrations​

Embedding Providers​

ProviderModelDimensionsCost/1K tokens
OpenAItext-embedding-3-small1536$0.00002
OpenAItext-embedding-3-large3072$0.00013
Anthropic/Voyagevoyage-31024$0.00006
Cohereembed-english-v3.01024$0.0001

Primary Selection: OpenAI text-embedding-3-small (best cost/performance)

Payment Processing​

ServicePurpose
StripeSubscription billing
Stripe ElementsPayment UI
Stripe WebhooksEvent processing

4. Security Stack​

Authentication & Authorization​

ComponentTechnology
Token FormatJWT (RS256)
Session ManagementRedis-backed
Password Hashingbcrypt
MFATOTP (future)
RBACCustom implementation

Network Security​

LayerProtection
TransportTLS 1.3
API GatewayCloud Armor (DDoS)
Rate LimitingRedis sliding window
CORSAllowlist origins

5. Observability Stack​

Monitoring​

ComponentTechnology
MetricsPrometheus + Grafana
LoggingGoogle Cloud Logging
TracingOpenTelemetry + Jaeger
AlertingPagerDuty/Slack

Key Metrics​

# API Metrics
api_request_duration_seconds
api_request_total
api_error_total

# Search Metrics
search_query_duration_seconds
search_results_count
embedding_generation_duration_seconds

# Database Metrics
db_connection_pool_size
db_query_duration_seconds

6. Development Tools​

Local Development​

ToolPurpose
Docker ComposeLocal services
Pre-commitGit hooks
pytestTesting
mypyType checking
ruffLinting + formatting

CI/CD Pipeline​

StageTools
BuildDocker, Cloud Build
Testpytest, vitest
Lintruff, eslint
SecuritySnyk, trivy
DeployTerraform, kubectl

7. Version Requirements Summary​

Backend​

PackageMinimum VersionNotes
Python3.11+Required for performance
FastAPI0.109+Pydantic V2 support
SQLAlchemy2.0+Async ORM
Pydantic2.5+V2 with improved performance
Celery5.3+Redis 7 support

Database​

SystemMinimum VersionNotes
PostgreSQL15+pgvector compatibility
pgvector0.5+HNSW index support
TimescaleDB2.13+Continuous aggregates
Redis7.0+Function support

Frontend​

PackageMinimum VersionNotes
Node.js20 LTSCurrent LTS
React18.2+Concurrent features
TypeScript5.3+Decorators, const enums
Vite5.0+Build performance

9. Revision History​

VersionDateAuthorChanges
1.0.02025-12-28Hal CasteelInitial SDD creation