Ref-008: Technical Specifications

Technical Specifications Reference

Document Type

Reference / Technical Specification

MVP Status

✅ MVP

Technology Stack

Languages & Runtimes

Technology	Version	Use Case
Python	3.11+	Knowledge Graph Service, Artifact Engine, Context Analyzer, Recommendation Algorithm, Domain Services
Node.js	20+	CALM CLI Service, Web Application frontend

Frameworks

Framework	Language	Use Case
FastAPI	Python	Microservices
Flask	Python	Legacy adapters
Oxigraph Driver	Python	Graph database access
PyTorch/TensorFlow	Python	ML models
React	Node.js	Web Application frontend
FINOS CALM	Node.js	CALM CLI

Gateway

Kong Gateway (OSS/Enterprise) with declarative configuration and plugin-based policies

Databases

Database	Version	Use Case
PostgreSQL	15+	Operational Data (Semantic Core, AI Agent Config)
Oxigraph	5+	Knowledge Graph Service

Infrastructure

Component	Technology
Container Runtime	Docker
Orchestration	Kubernetes (GKE, EKS, AKS)
Message Broker	RabbitMQ
Cloud	Cloud-agnostic

Integration Specifications

INT-001: Semantic Core & DSL Management Service API

Property	Value
Type	REST API (JSON)
Authentication	OAuth2/JWT
Data Format	JSON
Rate Limits	Configurable per client
Error Handling	Standard HTTP status codes (4xx/5xx) with detailed messages

Related Specs: ADR-002, PRD-001, PRD-003, SDS-002

INT-002: Knowledge Graph Service API

Property	Value
Type	GraphQL API, Bolt (Oxigraph native)
Authentication	OAuth2/JWT (GraphQL), Bolt auth (direct)
Data Format	JSON (GraphQL), native Bolt protocol
Rate Limits	Configurable per client
Error Handling	GraphQL error responses, Bolt driver exceptions

Related Specs: ADR-004, PRD-006, PRD-007, SDS-003

INT-003: Context Analyzer Service API

Property	Value
Type	gRPC (internal), REST API (JSON)
Authentication	Service mesh (gRPC), OAuth2/JWT (REST)
Data Format	Protobuf (gRPC), JSON (REST)
Rate Limits	Internal service limits
Error Handling	gRPC status codes, HTTP status codes

Related Specs: ADR-005, PRD-009, PRD-013, SDS-051

INT-004: Artifact Engine Service API

Property	Value
Type	gRPC (internal), REST API (JSON)
Authentication	Service mesh (gRPC), OAuth2/JWT (REST)
Data Format	Protobuf (gRPC), JSON (REST)
Rate Limits	Internal service limits
Error Handling	gRPC status codes, HTTP status codes

Related Specs: ADR-005, ADR-006, PRD-002, PRD-008, PRD-010, SDS-005

INT-005: CADSL Runtime & Renderer API

Property	Value
Type	WebSockets (real-time), REST API (JSON)
Authentication	OAuth2/JWT
Data Format	JSON (CADSL definitions)
Rate Limits	Configurable per client
Error Handling	WebSocket error frames, HTTP status codes

Related Specs: ADR-006, PRD-010, PRD-011, SDS-038

INT-006: CALM CLI Service

Property	Value
Type	Command Line Interface
Authentication	N/A (local), internal API integration
Data Format	CALM `.arch.json` files
Rate Limits	N/A
Error Handling	CLI error messages, exit codes

Related Specs: ADR-003, PRD-004, PRD-005, SDS-039

INT-007: AI Agent Configuration Service API

Property	Value
Type	REST API (JSON)
Authentication	OAuth2/JWT
Data Format	JSON
Rate Limits	Configurable per client
Error Handling	Standard HTTP status codes

Related Specs: ADR-007, PRD-012, PRD-013, SDS-040

INT-008: User Feedback Processor (Message Broker)

Property	Value
Type	Message Queue (Asynchronous)
Authentication	Message broker credentials
Data Format	JSON (UserInteractionFeedback schema)
Rate Limits	Managed by broker throughput
Error Handling	Dead-letter queues, retry mechanisms

Related Specs: ADR-008, PRD-014, PRD-015, SDS-009

INT-009: Documentation Orchestrator Service API

Property	Value
Type	REST API (JSON), gRPC (internal)
Authentication	OAuth2/JWT (REST), Service mesh (gRPC)
Data Format	JSON (REST), Protobuf (gRPC)
Rate Limits	Configurable per client
Error Handling	HTTP status codes, async status updates

Related Specs: ADR-009, PRD-016, SDS-036

INT-010: Project Context Analyzer Service API

Property	Value
Type	gRPC (internal), REST API (JSON)
Authentication	Service mesh (gRPC), OAuth2/JWT (REST)
Data Format	JSON (REST), Protobuf (gRPC)
Rate Limits	Internal limits, configurable for REST
Error Handling	gRPC status codes, graceful degradation

Related Specs: ADR-009, PRD-017, SDS-051

Security Specifications

SEC-001: Authentication and Authorization

Property	Value
Category	Authentication, Authorization
Implementation	OAuth2/JWT, Fine-grained RBAC
Standards	OWASP Top 10, NIST Cybersecurity Framework

Applies to: All user-facing features, SDS-002 to SDS-011

SEC-002: Data Encryption

Property	Value
Category	Encryption (Transit + Rest)
Implementation	TLS 1.2+ (transit), AES-256 (rest)
Key Management	HashiCorp Vault, AWS KMS
Standards	FIPS 140-2

Applies to: All data stores and network communication

SEC-003: Input Validation and Sanitization

Property	Value
Category	Input Validation
Implementation	Strict validation, parameterized queries, sandboxed execution
Standards	OWASP Top 10

Protections: SQL injection, XSS, command injection

SEC-004: Logging and Monitoring for Security Events

Property	Value
Category	Logging, Monitoring, Incident Response
Implementation	Centralized logging, real-time alerting, SIEM integration
Standards	ISO 27001

Events Logged: Auth failures, authorization denials, data access attempts

SEC-005: Secure AI Model Deployment and Inference

Property	Value
Category	AI Security
Implementation	Container scanning, env isolation, adversarial attack protection
Standards	Emerging AI security best practices

Protections: Model poisoning, adversarial attacks, data exfiltration

Performance Specifications

PERF-001: Semantic Core Query Latency

Property	Value
Metric	Average response time for semantic concept queries
Target	< 100ms for 95% of queries
Measurement	API Gateway metrics, service-level monitoring

Related: PRD-001, SDS-002

PERF-002: Knowledge Graph Query Latency

Property	Value
Metric	Average response time for complex graph traversal
Target	< 500ms for 90% of queries
Measurement	Knowledge Graph Service metrics, tracing

Related: PRD-006, PRD-007, SDS-003

PERF-003: Context Analysis Latency

Property	Value
Metric	Average time to analyze conversational context
Target	< 200ms for real-time interactions
Measurement	Context Analyzer Service metrics

Related: PRD-009, SDS-051

PERF-004: Cognitive Artifact Generation Latency

Property	Value
Metric	Average time from request to CADSL definition
Target	< 300ms
Measurement	Artifact Engine Service metrics

Related: PRD-002, PRD-010, SDS-005

PERF-005: CADSL Rendering Performance

Property	Value
Metric	Time to render complex artifact in UI
Target	< 500ms (initial), < 100ms (updates)
Measurement	Frontend performance monitoring

Related: PRD-011, SDS-038

PERF-006: AI Recommendation Latency

Property	Value
Metric	Average time to provide artifact recommendations
Target	< 250ms
Measurement	Recommendation Algorithm Service metrics

Related: PRD-009, SDS-039

PERF-007: Project Context Analysis Performance

Property	Value
Metric	Average time to analyze project and extract context
Target	< 5s (small), < 30s (medium), < 2min (large)
Measurement	Project Context Analyzer Service metrics

Size Brackets:

Small: < 10K LOC
Medium: < 100K LOC
Large: > 100K LOC

Related: PRD-017, SDS-051

PERF-008: Documentation Generation Performance

Property	Value
Metric	Average time to generate complete documentation
Target	< 10s (README), < 30s (comprehensive)
Measurement	Documentation Orchestrator Service metrics

Related: PRD-016, SDS-036

Deployment & Operations

Deployment Strategy

CI/CD: GitLab CI, GitHub Actions
Strategy: Blue-green or rolling deployments
Platform: Kubernetes
Principles: Immutable infrastructure

Monitoring Stack

Component	Technology
Instrumentation	OpenTelemetry SDK
Pipeline	OTel Collector
Backend	OpenObserve (metrics, logs, traces)
Compliance	Vanta (SOC2, ISO 27001)
Python Logging	Logfire
Observability	SLOs and SLIs for all critical services

Logging Standards

Format: Structured JSON
Ingestion: Centralized logging system
Retention: Compliance-based policies

Backup & Recovery

Property	Specification
Frequency	Automated daily backups
Scope	PostgreSQL, Oxigraph
RPO/RTO	Defined per data classification
DR Plan	Active with regular testing

Traceability Summary

Specification Type	Coverage
ADRs	ADR-001 to ADR-009
PRDs	PRD-001 to PRD-017
SDS	SDS-001 to SDS-040

This document provides technical specifications that directly implement architectural decisions (ADRs), satisfy product requirements (PRDs), and detail software design (SDSs).