Technical

Technical Architecture Skill

Provides comprehensive guidance on technical architecture and implementation decisions for full-stack applications, from system design to technology selection.

Quick Decision Guide

What do you need?

System architecture / Tech stack selection
  → Use: THIS skill (overall architecture, technology choices)

Security architecture / Threat modeling
  → Use: security skill (security patterns, compliance, risk)

Code review / Code quality
  → Use: code-review skill (line-by-line review, vulnerabilities)

CI/CD pipeline / Infrastructure / Deployment
  → Use: devops skill (pipelines, containers, monitoring)

UI/UX design / Wireframes / Mockups
  → Use: ux skill (user interface design, user flows)

Product planning / Feature prioritization
  → Use: product-owner skill (roadmap, user stories, backlog)

Scope of This Skill

This Skill Covers (Technical Architecture)

• ✅ Overall system architecture and service design
• ✅ Component architecture and code organization
• ✅ API design (REST, GraphQL, tRPC)
• ✅ Database schema and data modeling
• ✅ State management patterns
• ✅ Technology stack selection
• ✅ Performance optimization strategy
• ✅ Caching architecture
• ✅ Scalability planning
• ✅ Third-party service integration
• ✅ Frontend and backend patterns

Use Other Skills For

• ❌ Security architecture → Use security skill
• ❌ Code security review → Use code-review skill
• ❌ CI/CD pipelines → Use devops skill
• ❌ Infrastructure setup → Use devops skill
• ❌ UI/UX design → Use ux skill
• ❌ Product planning → Use product-owner skill

This Skill Works With Other Skills

• security skill → Technical arch provides structure, security validates it
• code-review skill → Technical arch defines patterns, code-review ensures compliance
• devops skill → Technical arch chooses stack, devops deploys it
• ux skill → UX defines user needs, technical arch implements them

Pre-Planning Checklist

Before starting architectural planning, gather:

Requirements

• [ ] What problem are we solving?
• [ ] Who are the users? (Students, teachers, admins, public)
• [ ] What are the core features?
• [ ] What's the expected scale? (users, data volume, traffic)
• [ ] What's the timeline? (MVP in weeks vs production in months)

Constraints

• [ ] Budget limitations?
• [ ] Team skills and size?
• [ ] Performance requirements? (response time, throughput)
• [ ] Compliance requirements? (GDPR, HIPAA, etc.)
• [ ] Integration requirements? (existing systems, APIs)

Context

• [ ] Starting from scratch or evolving existing system?
• [ ] Mobile, web, or both?
• [ ] Real-time features needed?
• [ ] Offline support needed?
• [ ] Global users or regional?

References to Load

• [ ] Frontend decisions → references/frontend-patterns.md
• [ ] Backend decisions → references/backend-patterns.md
• [ ] Database design → references/database-design.md
• [ ] Deployment/hosting → references/deployment-systems.md

Architecture Decision Framework

1. Understand Requirements

Start with the pre-planning checklist above.

2. Choose Architecture Pattern

Based on your stage and needs, select the appropriate pattern:

For MVPs / New Products:

• Pattern 1: Serverless Full-Stack (fast iteration, low maintenance)

For Growing Products:

• Pattern 3: Hybrid (pragmatic middle ground)

For Established Products:

• Pattern 2: Containerized Microservices (full control, scale)

See "Common Architecture Patterns" section below for details.

3. Select Technologies

Consult reference files for detailed guidance:

• Frontend: references/frontend-patterns.md
• Backend: references/backend-patterns.md
• Database: references/database-design.md
• Deployment: references/deployment-systems.md

4. Validate with Other Skills

Security validation:

• Use security skill to threat model your architecture
• Review authentication/authorization patterns
• Validate data protection approach

Code organization validation:

• Use code-review skill to establish coding standards
• Define maintainability criteria

Deployment validation:

• Use devops skill to design CI/CD pipeline
• Plan infrastructure and monitoring

5. Evaluate Tradeoffs

Every architecture decision involves tradeoffs:

Complexity vs Flexibility:

• Simple solutions are easier to maintain
• Complex solutions offer more flexibility
• Rule: Choose simplest solution that meets requirements

Performance vs Development Speed:

• Optimizations take time to implement
• Premature optimization wastes effort
• Rule: Optimize based on actual bottlenecks, not assumptions

Cost vs Scale:

• Serverless: Low cost at low scale, expensive at high scale
• Dedicated servers: Higher baseline cost, cheaper at scale
• Rule: Choose based on expected traffic patterns

Vendor Lock-in vs Convenience:

• Managed services (Vercel, Supabase) are convenient but lock you in
• Self-hosted solutions give flexibility but require maintenance
• Rule: Consider long-term strategic value and exit cost

Build vs Buy:

• Building gives control but takes time
• Buying gets you features fast but adds dependencies
• Rule: Buy for non-core features, build for competitive advantages

Common Architecture Patterns

Pattern 1: Serverless Full-Stack (Recommended for MVPs)

Stack:

Frontend:    Next.js on Vercel
Backend:     Next.js API Routes (serverless functions)
Database:    Supabase (PostgreSQL) or PlanetScale (MySQL)
Cache:       Upstash Redis
File Storage: Vercel Blob or S3
Auth:        NextAuth.js or Clerk

When to use:

• ✅ New products/MVPs
• ✅ Small to medium scale ( $500/month at scale)
• Some vendor lock-in (but manageable)
• Cold start latency (200-500ms first request)
• Limited control over infrastructure

Migration path: When you outgrow this, move to Pattern 3 (Hybrid)

---

Pattern 2: Containerized Microservices (For Scale)

Stack:

Frontend:    Next.js in containers (ECS/Kubernetes)
Backend:     Node.js services in containers
Database:    RDS PostgreSQL with read replicas
Cache:       ElastiCache Redis
File Storage: S3
Auth:        Custom JWT implementation
Message Queue: SQS or RabbitMQ

When to use:

• ✅ Proven product with growth (> 100k users)
• ✅ Need more control over infrastructure
• ✅ Complex business logic requiring service isolation
• ✅ Team has DevOps skills
• ✅ Predictable high traffic

Pros:

• Full control over infrastructure
• Better cost at scale ($500-2k/month for high traffic)
• Service isolation (can scale services independently)
• Technology flexibility (mix languages)
• No cold starts

Cons:

• More complex setup (weeks of infrastructure work)
• Requires DevOps expertise
• Higher baseline costs (minimum ~$200/month)
• More maintenance burden

Migration path: Usually don't migrate away, just add more services

---

Pattern 3: Hybrid (Pragmatic Middle Ground)

Stack:

Frontend:    Next.js on Vercel (fast deploys, edge)
Backend:     Dedicated API server on Railway/Render/Fly.io
Database:    Managed PostgreSQL (Supabase/Neon/RDS)
Cache:       Upstash Redis or managed Redis
File Storage: S3 or Cloudflare R2
Auth:        NextAuth.js or custom

When to use:

• ✅ Outgrowing serverless costs (> $300/month)
• ✅ Not ready for full container complexity
• ✅ Need more backend flexibility (long-running tasks)
• ✅ Want good DX with more control
• ✅ Growing team (2-5 developers)

Pros:

• Better cost than pure serverless at scale
• More backend control (background jobs, websockets)
• Frontend still has great DX (Vercel)
• Easier than full microservices
• Good balance of control and convenience

Cons:

• More complex than pure serverless
• Need to manage API server
• Not as automated as Pattern 1
• Not as flexible as Pattern 2

Migration path: Can move to Pattern 2 when you need service isolation

---

Technology Selection Guidelines

Frontend Framework

Next.js (Recommended):

• ✅ Full-stack capabilities (API routes, server actions)
• ✅ Excellent performance (SSR, ISR, SSG)
• ✅ Great DX with Vercel
• ✅ Large ecosystem and community
• ✅ Built-in optimizations (images, fonts, code splitting)
• Use for: Most web applications, SEO-critical sites

React SPA:

• ✅ Simple deployment (static files)
• ✅ Full client-side control
• ✅ Works well with any backend
• ❌ Worse SEO (unless prerendering)
• ❌ Slower initial load
• Use for: Admin dashboards, internal tools, web apps where SEO doesn't matter

React Native (Mobile):

• ✅ Code sharing with web (if using React)
• ✅ Native performance
• ✅ Single codebase for iOS + Android
• ❌ More complex than web
• ❌ App store deployment overhead
• Use for: Mobile apps (student/guardian apps for educational app)

---

Backend Language/Runtime

Node.js/TypeScript (Recommended):

• ✅ Share code and types with frontend
• ✅ Great ecosystem (npm packages)
• ✅ Fast development (familiar to frontend devs)
• ✅ Good for I/O-heavy tasks (APIs, databases)
• ✅ Async by default
• Use for: Most applications, especially full-stack TypeScript

Python:

• ✅ Excellent for ML/AI workloads
• ✅ Great data processing libraries (pandas, numpy)
• ✅ Good for scripts and background jobs
• ❌ Harder to share code with frontend
• ❌ Slower for I/O-heavy tasks
• Use for: ML pipelines, data processing, computer vision, background jobs

When to use both:

• Node.js for API server (user-facing)
• Python for background processing (ML, data analysis)

---

Database

PostgreSQL (Recommended for most apps):

• ✅ Excellent for relational data
• ✅ ACID transactions (data integrity)
• ✅ Rich query capabilities (joins, aggregations)
• ✅ JSON support for flexibility
• ✅ Great performance with proper indexing
• ✅ Mature ecosystem
• Use for: Educational apps, CRUDs, any structured data

MongoDB:

• ✅ Flexible schema (good for rapid prototyping)
• ✅ Fast writes
• ✅ Good for unstructured data
• ❌ Weaker consistency guarantees
• ❌ No joins (application-level only)
• Use for: Rapid prototyping, analytics, logs, event data

Decision matrix:

• Structured data with relationships? → PostgreSQL
• Need ACID transactions? → PostgreSQL
• Flexible/evolving schema? → MongoDB or PostgreSQL (with JSONB)
• Heavy analytics? → PostgreSQL (with indexing) or ClickHouse

For detailed schema design, consult references/database-design.md

---

State Management

React Query/SWR (Recommended for server state):

• ✅ Handles 90% of state needs
• ✅ Automatic caching and refetching
• ✅ Loading/error states handled
• ✅ Less boilerplate than Redux
• ✅ Optimistic updates
• Use for: API data, server state, any data from backend

Zustand (Recommended for client state):

• ✅ Simple API
• ✅ Small bundle size ( 5 people

Approach:

1. Identify service boundaries (auth, payments, notifications)
2. Extract one service at a time (start with least critical)
3. Add message queue (SQS, RabbitMQ) for async communication
4. Set up service mesh (if using Kubernetes)
5. Add centralized logging and monitoring

Timeline: 1-3 months

---

From Monorepo to Multiple Repos

When: Team > 10 people, clear service ownership

Approach:

1. Extract shared code to npm packages
2. Split services into separate repos
3. Set up consistent CI/CD across repos
4. Use dependency management (Renovate, Dependabot)

Timeline: 2-4 weeks

---

Getting Started

New Project Workflow

1. Define requirements (use pre-planning checklist)
2. Choose architecture pattern (serverless/hybrid/microservices)
3. Select technologies (consult reference files)
4. Design data model (references/database-design.md)
5. Plan API structure (references/backend-patterns.md)
6. Design frontend (references/frontend-patterns.md)
7. Validate with security skill (threat model, security controls)
8. Set up with devops skill (CI/CD, infrastructure)
9. Document decisions (ADRs - Architecture Decision Records)

Existing Project Review Workflow

1. Understand current architecture (diagram, document)
2. Identify pain points (slow, expensive, hard to maintain)
3. Assess against checklist (above)
4. Identify gaps (missing caching, poor indexes, etc.)
5. Propose improvements (prioritized by impact)
6. Create migration plan (phased approach)
7. Validate with other skills (security, code-review, devops)

---

Requesting Architectural Guidance

For best results, provide:

Context:

• What you're building (brief description)
• Current state (greenfield vs existing system)
• Team size and skills

Specific Question:

• What decision are you trying to make?
• What options are you considering?
• What's the tradeoff you're evaluating?

Constraints:

• Budget ($ per month)
• Timeline (MVP in 2 weeks vs production in 3 months)
• Scale requirements (expected users, traffic)
• Compliance (GDPR, HIPAA, etc.)

Example: > "I'm building an educational app for 1000 students and 50 teachers. Need task management, calendar, and file uploads. Team is 2 developers with React/Node.js skills. Budget is $100/month. Need MVP in 4 weeks. Should I use serverless or dedicated backend?"

This skill will consult the relevant references and provide context-specific, actionable recommendations.

---

Reference Files

Load these for detailed guidance:

• references/frontend-patterns.md - React/Next.js patterns, state management, performance
• references/backend-patterns.md - API design, authentication, caching, background jobs
• references/database-design.md - Schema design, indexing, migrations, scaling
• references/deployment-systems.md - Hosting platforms, CI/CD, monitoring

For comprehensive coverage, use with:

• security skill - Security architecture, threat modeling, compliance
• code-review skill - Code quality, testing strategy, maintainability
• devops skill - CI/CD pipelines, infrastructure, deployment
• ux skill - User interface design, user flows, wireframes

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tomas-u
• Source: tomas-u/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.