System Architecture

How Tesseric Works - Built for Scale, Security, and Speed

8.0s

Average Response Time

Bedrock AI analysis + Neo4j write

98.7%

Graph Write Success

Async background writes to Neo4j

Zero

Data Persistence

Ephemeral sessions, immediate discard

100%

Type Safe

TypeScript + Pydantic strict mode

Technology Stack

Why we chose these technologies, what alternatives we considered, and the trade-offs we accepted

⚛️

Next.js 14 + TypeScript

React framework with server components and full-stack capabilities

Why We Chose It

Server Components reduce bundle size, App Router provides intuitive routing, built-in TypeScript support catches errors at compile time, and exceptional developer experience with fast refresh. Vercel deployment is seamless.

🐍

FastAPI + Python 3.11

High-performance async Python framework with automatic OpenAPI docs

Why We Chose It

Async by default (handles concurrent requests efficiently), automatic OpenAPI documentation at /docs, Pydantic v2 for request/response validation (type-safe at runtime), excellent AWS SDK support (boto3), and fast development iteration.

🤖

AWS Bedrock (Claude 3.5 Haiku)

AWS-native AI service with Claude models for architecture analysis

Why We Chose It

AWS-native integration (lowest latency from Railway), cost-effective at ~$0.001 per text review (~$0.012 with vision), inline context approach avoids $700/month Knowledge Base costs, and Claude 3.5 Haiku provides excellent quality-to-cost ratio.

🕸️

Neo4j AuraDB

Native graph database for AWS service relationships and pattern analysis

Why We Chose It

Native graph relationships (not SQL joins), Cypher query language is expressive for pattern matching, visual topology extraction (Phase 2.3), accumulates knowledge across reviews (CO_OCCURS_WITH relationships), and free tier (200K nodes, 400K edges) is generous.

🚂

Railway (Backend) + Vercel (Frontend)

Simple deployment platforms with generous free tiers and Git integration

Why We Chose It

Railway: Dockerfile support, automatic deployments from GitHub, built-in secrets management, $5-10/month backend hosting. Vercel: Serverless Next.js hosting, instant CDN, zero-config deployments, $0/month for hobby projects.

All technologies chosen with cost, performance, and developer experience in mind.
See decisions.log.md for full ADRs (Architectural Decision Records).

Data Flow & Request Lifecycle

Follow a review request from submission to display (9 steps, ~2-10s total)

User Submits Architecture

~0ms

API Call to Backend

~50-100ms

Input Validation

~10ms

Token Estimation

~5ms

AWS Bedrock Invocation

~2-8s

Response Parsing

~20ms

Neo4j Write (Async)

~200-500ms

Return Response

~5ms

Display Results

~50ms

9

Total Steps

2-10s

End-to-End Time

~8.0s

Avg Production Time

Async

Neo4j Writes

Security Architecture

Defense-in-depth with zero-trust principles

No Data Storage

Ephemeral sessions with immediate discard. Architecture descriptions never touch a database. GDPR compliant by design.

✅ Implemented

HTTPS Everywhere

TLS 1.3 for all connections. Vercel and Railway enforce HTTPS by default. No mixed content warnings.

✅ Implemented

IAM Roles Only

AWS Bedrock accessed via IAM roles in Railway environment. No hardcoded access keys in codebase or Docker images.

✅ Implemented

Input Validation

Pydantic v2 schemas validate all inputs. XSS protection via framework defaults. Field-level constraints enforced.

✅ Implemented

CORS Whitelist

Restricted origins: tesseric.ca and api.tesseric.ca only. No wildcard (*) in production. Preflight requests validated.

✅ Implemented

Rate Limiting

Coming soon: 10 req/min per IP for /review, 60 req/min for /api/metrics. Prevents API abuse and cost overruns.

🚧 Roadmap (TASK-011)

Security Boundaries

┌─────────────────────────────────────────────────────────────────┐
│                         User / Browser                          │
│                   (HTTPS only, TLS 1.3)                         │
└────────────────────────────┬────────────────────────────────────┘
                             │ Trusted
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Vercel (Frontend CDN)                        │
│              • Origin whitelisted (tesseric.ca)                 │
│              • Auto SSL certificates                            │
│              • DDoS protection built-in                         │
└────────────────────────────┬────────────────────────────────────┘
                             │ CORS validated
                             │ (tesseric.ca → api.tesseric.ca)
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                Railway (Backend API)                            │
│              • HTTPS-only endpoints                             │
│              • Environment secrets encrypted                    │
│              • No public IP (Railway internal)                  │
└───────────────┬──────────────────────┬──────────────────────────┘
                │ IAM role            │ Connection string
                │ (no keys)           │ (env variable)
                ▼                     ▼
┌────────────────────┐       ┌─────────────────────────┐
│   AWS Bedrock      │       │   Neo4j AuraDB          │
│   (us-east-2)      │       │   (Cloud-managed)       │
│                    │       │                         │
│ • IAM role auth    │       │ • TLS connection        │
│ • Regional service │       │ • Encrypted at rest     │
│ • AWS-managed keys │       │ • Automatic backups     │
└────────────────────┘       └─────────────────────────┘
Trusted boundary
CORS validated
IAM authenticated
TLS encrypted

AWS Well-Architected Security Pillar Alignment

✅ Identity & Access Management

IAM roles for Bedrock (principle of least privilege)

✅ Detective Controls

Logging enabled for all API requests (Railway logs)

✅ Data Protection

Zero persistence + TLS everywhere + Neo4j encryption at rest

✅ Infrastructure Protection

CORS whitelist, Pydantic validation, HTTPS-only

See AWS Security Pillar for full best practices

Future Architecture

What's next on the roadmap with architectural implications

Multi-Cloud Support

Phase 3Q2 2026

Extend beyond AWS to analyze Azure and GCP architectures. Provider-agnostic Well-Architected principles.

Architecture Impact
  • Abstract provider-specific logic into plugins (aws/, azure/, gcp/)
  • Common taxonomy mapping (AWS pillars → Azure WAF → GCP Architecture Framework)
  • Multi-region inference profile selection per provider

Real-Time Collaboration

Phase 4Q3 2026

Multiple users review same architecture simultaneously. WebSocket-based live cursors and annotations.

Architecture Impact
  • WebSocket server on backend (Socket.IO or native WebSockets)
  • Redis for session state and presence tracking
  • Frontend state sync with Zustand or Jotai

IaC Analysis

Phase 4Q3 2026

Paste Terraform or CloudFormation templates. Parse resources, detect misconfigurations, suggest improvements.

Architecture Impact
  • HCL parser for Terraform (terraform-json)
  • CloudFormation JSON/YAML parser
  • Map resources to Well-Architected checks (e.g., S3 without encryption)

CLI Tool

Phase 5Q4 2026

tesseric review architecture.md --tone=roast --output=json. CI/CD integration for automated reviews.

Architecture Impact
  • Python CLI with Click or Typer
  • Local config file (.tesseric.yml) for defaults
  • GitHub Actions workflow for PR comments

Team Accounts & SSO

Phase 5Q4 2026

Multi-tenant architecture with team workspaces. SAML/OIDC integration for enterprise.

Architecture Impact
  • Auth layer: AWS Cognito or Auth0
  • DynamoDB table for organizations and memberships
  • Row-level security for Neo4j queries

Future State Architecture (v2.0 Vision)

Want to influence the roadmap? We're open to feedback and feature requests.

View Full Roadmap