C1: System Context Diagram - CODITECT Cloud Infrastructure
Level: System Context (C4 Model Level 1) Scope: Complete CODITECT Cloud Infrastructure Ecosystem Primary Audience: Executives, Product Managers, External Stakeholders Last Updated: November 23, 2025
Overview
The System Context diagram provides a high-level view of the CODITECT cloud infrastructure, showing how it fits into the broader ecosystem and interacts with external systems and users.
Key Insight: CODITECT operates as a hybrid architecture - the core application runs locally on user machines (local-first), while the cloud infrastructure provides licensing, authentication, session management, and optional collaboration features.
System Context Diagram
System Actors
Primary Users
| Actor | Description | Interaction Pattern |
|---|---|---|
| Developer (CODITECT User) | Software developer using CODITECT locally for AI-assisted development | Check-on-start license validation, heartbeat every 5 minutes, graceful shutdown |
| System Administrator | DevOps/SRE managing cloud infrastructure | Deploy updates, monitor health, scale resources, troubleshoot issues |
| End User (Dashboard) | Business user accessing web dashboard for license management | View analytics, manage team seats, download reports |
External Systems
| System | Technology | Purpose | Integration Type |
|---|---|---|---|
| LLM Providers | OpenAI, Anthropic, Google, Ollama, LMStudio | AI content generation for CODITECT users | REST API (user-initiated) |
| Google Cloud Platform | GCP Managed Services | Infrastructure hosting and managed services | Native GCP APIs |
| Payment Processing | Stripe | Subscription billing and payment webhooks | Webhook + REST API |
| Email Service | SendGrid | Transactional emails (license delivery, alerts) | REST API |
| External Monitoring | PagerDuty, Sentry | Incident management and error tracking | Webhook + REST API |
| Version Control | GitHub | Source code hosting and CI/CD automation | GitHub Actions |
System Boundaries
What's Inside CODITECT Cloud Infrastructure
Core Responsibilities:
- License key generation and validation
- User authentication and authorization (OAuth2 + JWT)
- Session tracking with TTL-based expiration
- Multi-tenant data isolation
- License signature verification (RSA-4096)
- Hardware fingerprinting (device binding)
- Usage analytics and reporting
- API rate limiting and throttling
Technology Stack:
- Runtime: Google Kubernetes Engine (GKE)
- API Framework: FastAPI (Python async)
- Database: Cloud SQL PostgreSQL 16
- Cache: Cloud Memorystore Redis 7.x
- Authentication: Identity Platform (Firebase Auth)
- License Signing: Cloud KMS (RSA-4096 keys)
- Infrastructure as Code: OpenTofu 1.6.7
What's Outside (External Dependencies)
Not Included in This System:
- CODITECT application itself (runs on user's machine)
- LLM provider infrastructure (third-party APIs)
- Payment processing logic (handled by Stripe)
- Email delivery infrastructure (handled by SendGrid)
- DNS management (Cloud DNS is external to application logic)
Key Architectural Decisions
ADR-001: Local-First Architecture
Decision: CODITECT application runs entirely on user's machine, with cloud infrastructure providing licensing and optional collaboration only.
Rationale:
- Performance: No network latency for core development workflows
- Privacy: User code never leaves their machine
- Offline Capability: 24-hour grace period for intermittent connectivity
- Cost Efficiency: Reduces cloud compute costs significantly
Trade-offs:
- Requires desktop application installation
- License validation adds startup delay (~500ms)
- Heartbeat mechanism needed for session tracking
ADR-002: GCP-Only Cloud Provider
Decision: Use Google Cloud Platform exclusively for all cloud infrastructure.
Rationale:
- Simplified Operations: Single cloud provider reduces complexity
- Integrated Services: Tight integration between GKE, Cloud SQL, Memorystore
- Cost Predictability: GCP committed use discounts (up to 57% savings)
- Security: Cloud KMS native integration for license signing
- Compliance: HIPAA, SOC 2, ISO 27001 certifications
Trade-offs:
- Vendor lock-in to GCP
- Multi-region deployment requires manual replication
- No cloud redundancy (single point of failure)
ADR-003: Check-on-Start License Pattern
Decision: Validate license at application startup, then use heartbeat mechanism for session tracking.
Rationale:
- User Experience: Minimal friction (one-time check per session)
- Security: Prevents license sharing via hardware fingerprinting
- Reliability: Graceful degradation with 24-hour grace period
- Seat Management: Automatic TTL-based seat release (6 minutes)
Trade-offs:
- Requires internet connection at startup
- Heartbeat mechanism adds background network traffic
- Grace period could enable temporary license sharing
Data Flow Overview
License Acquisition Flow
User starts CODITECT
↓
License Client SDK → License API (HTTPS)
↓
API validates: License Key + Hardware Fingerprint + Seat Availability
↓
PostgreSQL: Check license record, seat count
↓
Redis: Atomic seat allocation (Lua script)
↓
Cloud KMS: Sign license token (RSA-4096)
↓
Return signed JWT → CODITECT stores locally
↓
Application runs with offline capability
Heartbeat Mechanism
Every 5 minutes (background thread):
↓
License Client SDK → License API (HTTPS)
↓
API validates JWT signature
↓
Redis: EXPIRE session key (6 minutes TTL)
↓
Return 200 OK
↓
Continue running
Session Cleanup
User closes CODITECT gracefully:
↓
SDK → License API: DELETE /api/v1/licenses/release
↓
Redis: DEL session key
↓
Seat immediately available
OR
User crashes / network disconnects:
↓
Heartbeat stops
↓
Redis TTL expires after 6 minutes
↓
Seat automatically released
Security Architecture
Defense-in-Depth Strategy
Layer 1: Network Security
- Private GKE cluster (no public node IPs)
- Cloud Armor WAF (DDoS protection, rate limiting)
- VPC peering for Cloud SQL (no public database access)
- Cloud NAT for egress traffic
Layer 2: Authentication & Authorization
- Identity Platform (Firebase Auth) for OAuth2
- JWT tokens with RS256 signatures
- Cloud KMS for license token signing
- Hardware fingerprinting to prevent license sharing
Layer 3: Application Security
- API rate limiting (100 req/min per user)
- Input validation and sanitization
- SQL injection prevention (parameterized queries)
- Secrets in GCP Secret Manager (never in code)
Layer 4: Data Security
- Encryption at rest (Cloud SQL, Redis)
- Encryption in transit (TLS 1.3)
- Row-level security for multi-tenant isolation
- Audit logging for compliance
Layer 5: Monitoring & Response
- Real-time intrusion detection
- Anomaly detection (unusual seat allocations)
- Automated incident response (circuit breakers)
- PagerDuty integration for critical alerts
Scalability Characteristics
Current Capacity (Development)
| Metric | Current Configuration | Maximum Throughput |
|---|---|---|
| GKE Nodes | 3x n1-standard-2 (preemptible) | ~100 concurrent users |
| Cloud SQL | db-custom-2-7680 (2 vCPU, 7.68GB) | ~100 connections, 500 QPS |
| Redis | 6GB BASIC tier | ~50K ops/sec |
| API Latency | ~50ms p95 (local region) | 100 req/sec per pod |
Production Target (10,000 users)
| Metric | Target Configuration | Expected Throughput |
|---|---|---|
| GKE Nodes | 10x n1-standard-4 (auto-scaling) | ~10,000 concurrent users |
| Cloud SQL | db-custom-8-32768 (8 vCPU, 32GB) | ~1,000 connections, 10K QPS |
| Redis | 16GB STANDARD HA tier | ~500K ops/sec |
| API Latency | ~20ms p95 (CDN + regional replicas) | 1,000 req/sec aggregate |
Cost Analysis
Current Infrastructure Costs (Development)
| Component | Monthly Cost | Annual Cost |
|---|---|---|
| GKE Cluster (3x preemptible nodes) | $100 | $1,200 |
| Cloud SQL PostgreSQL (Regional HA) | $150 | $1,800 |
| Redis Memorystore (6GB BASIC) | $30 | $360 |
| Networking (Cloud NAT, egress) | $20 | $240 |
| Secret Manager | $5 | $60 |
| Total Development | $310/month | $3,720/year |
Production Infrastructure Costs (10K users)
| Component | Monthly Cost | Annual Cost |
|---|---|---|
| GKE Cluster (10x standard nodes) | $500 | $6,000 |
| Cloud SQL PostgreSQL (HA, 8 vCPU) | $400 | $4,800 |
| Redis Memorystore (16GB STANDARD HA) | $150 | $1,800 |
| Cloud KMS | $10 | $120 |
| Identity Platform (50K MAU) | $50 | $600 |
| Cloud Load Balancer + SSL | $50 | $600 |
| Monitoring (Prometheus, Grafana) | $40 | $480 |
| Total Production | $1,200/month | $14,400/year |
Cost per User (Production): $1.20/month per active user
Technology Choices Rationale
Why Google Cloud Platform?
Strengths:
- Best-in-class Kubernetes (GKE is Kubernetes' birthplace)
- Managed PostgreSQL with automatic HA failover
- Tight integration (VPC peering, Workload Identity)
- Competitive pricing with committed use discounts
- Strong compliance certifications
Considered Alternatives:
- AWS: More mature, but higher complexity for Kubernetes
- Azure: Strong enterprise support, but limited GKE equivalent
- Multi-Cloud: Rejected due to operational complexity
Why OpenTofu over Terraform?
Rationale:
- Open-source alternative to HashiCorp Terraform
- 100% compatible with Terraform modules
- Community-driven development
- No licensing concerns for future commercial use
Why FastAPI over Django/Flask?
Rationale:
- Performance: Async/await for high concurrency
- Type Safety: Pydantic models prevent runtime errors
- Documentation: Auto-generated OpenAPI/Swagger docs
- Speed: 3x faster than Flask, comparable to Node.js
Considered Alternatives:
- Django: Too heavy for microservices, synchronous only
- Flask: Lacks async support, manual validation
- Go/Rust: Longer development time, smaller talent pool
Success Metrics
Reliability (SLOs)
| Metric | Target | Measurement |
|---|---|---|
| API Availability | 99.9% | Uptime monitoring (PagerDuty) |
| License Acquisition Latency | <500ms p95 | Prometheus histogram |
| Heartbeat Success Rate | >99.5% | Redis TTL expiration rate |
| Database Query Latency | <10ms p95 | Cloud SQL insights |
Performance (KPIs)
| Metric | Target | Current |
|---|---|---|
| Concurrent Users | 10,000 | ~10 (dev) |
| Seat Allocation Time | <100ms | ~50ms |
| License Validation Time | <200ms | ~80ms |
| API Throughput | 1,000 req/sec | ~10 req/sec |
Business Metrics
| Metric | Target | Tracking |
|---|---|---|
| User Retention | >80% monthly | PostgreSQL analytics |
| Average Session Duration | >4 hours | Redis session logs |
| Seat Utilization | >70% | Tenant-level reports |
| License Renewals | >90% | Stripe subscription webhooks |
Related Diagrams
- C2: Container Diagram - Internal system components
- C3: GKE Component Diagram - Kubernetes infrastructure
- C3: Networking Components - VPC and network security
- C3: Security Components - Authentication and encryption
Document History
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0 | 2025-11-23 | SDD Architect | Initial C1 System Context diagram |
Document Classification: Internal - Architecture Documentation Review Cycle: Quarterly (or upon major architectural changes) Next Review Date: 2026-02-23