Módulo 8: Integrator Project — Capstone Architecture Design

Proyecto final: Capstone Architecture Design Document

Descripción

Llegaste al final del path. Este proyecto consolida todo: M1-M7 + las cápsulas anteriores de M8 (01-07). Producís el Capstone Architecture Design Document completo: el deliverable que llevás a tu portfolio, que mostrás en entrevistas, y que vas a usar como blueprint para implementar el Capstone real.

Es el documento más ambicioso del path. 30-50 páginas. Suena mucho, pero recordá: vos ya produjiste partes de él en cápsulas anteriores. Acá las integras + agregás algunas piezas finales.

Al terminar vas a tener:

  • Capstone Architecture Design Document completo en Markdown
  • Diagramas C4 en tres niveles
  • 6-8 Architecture Decisions documentadas
  • RAG + Agent + Integration designs
  • Scaling + Reliability strategies
  • Cost projection completa
  • Implementation checklist (sprints + milestones)
  • Risks and mitigations

Estructura del documento final

# AI-Powered Knowledge Assistant — Architecture Design Document

**Version**: 1.0
**Date**: 2026-MM-DD
**Author**: [Your name]
**Reviewers**: [CTO, peers]

## Table of Contents

1. Executive Summary
2. System Overview
3. C4 Diagrams (Context, Container, Component)
4. RAG Pipeline Design
5. Agent Layer Design
6. Integration Layer
7. Scaling Strategy
8. Reliability Design
9. Architecture Decisions (6-8 ADRs)
10. Cost Projection (Year 1, Year 2)
11. Implementation Checklist
12. Risks and Mitigations
13. Appendices

Section-by-section guide

Section 1: Executive Summary (1 page)

Audience: cofounders, executives, non-technical stakeholders.

## Executive Summary

The AI-Powered Knowledge Assistant is a multi-tenant SaaS that helps
employees of enterprise clients quickly find answers to technical and
process questions, with citations to internal sources.

Architecture highlights:
- Multi-tenant from day 1 (50 tenants target Year 1)
- Slack as primary channel (Discord on roadmap)
- Agentic RAG with MCP for external tool integration
- Designed for 99.5% uptime, P95 latency <8s
- Year 1 monthly cost: $1,070 → $3,530 (5-50 tenants growth)
- Year 2 monthly cost: ~$11,700 at 100 tenants, 5M queries/mo
- Margins: 47% → 72% improvement across Year 1

Stack:
- LLM: OpenAI (gpt-4o-mini + gpt-4o routing)
- Vector DB: Pinecone managed
- Hosting: Cloud Run (web) + ECS (workers)
- Agent: LangGraph
- Channel: Slack (via Bolt for Python)

Implementation timeline: 6-8 sprints (~16 weeks) to v1 production.

Key risks: vendor lock-in (OpenAI), scaling LLM costs, compliance gaps.
Mitigations: multi-provider Tier 2, cost monitoring + budget caps,
compliance flexibility built-in.

Section 2: System Overview (1-2 pages)

## System Overview

### Problem

Enterprise employees spend 10-30% of work time searching for information
across internal docs, wikis, GitHub, Linear. Existing search tools are
limited to keyword matching and don't synthesize information across sources.

### Solution

AI assistant accessible via Slack that:
- Answers questions using internal knowledge base (RAG)
- Searches GitHub, Notion, Linear via MCP servers
- Maintains conversation context within Slack threads
- Provides citations to source documents
- Learns from feedback (👍/👎) to improve over time

### Users

- **Employees**: ask questions, give feedback
- **Admins**: install app, configure knowledge bases, monitor usage

### Constraints

- **Compliance**: SOC2 required, HIPAA capability for 2 prospects
- **Budget**: $5K/mo Year 1
- **Performance**: P95 <8s, 99.5% uptime
- **Multi-tenant**: 5 → 50 → 100 tenants growth
- **Privacy**: tenant data fully isolated

Section 3: C4 Diagrams (3-5 pages)

Reuse from M8-02. Include all 3 levels (Context, Container, Component) with descriptions.

Section 4: RAG Pipeline Design (2-3 pages)

Reuse from M8-03. Include:

  • Sources supported (Notion, GitHub, Linear, PDF)
  • Chunking strategy
  • Embedding model + cost
  • Vector DB choice
  • Retrieval strategy
  • Reranking
  • Citations approach
  • Quality metrics

Section 5: Agent Layer Design (2-3 pages)

Reuse from M8-04. Include:

  • Tools available
  • Framework (LangGraph)
  • State machine diagram
  • Tool routing strategy
  • Multi-step reasoning
  • Self-correction
  • Memory

Section 6: Integration Layer (2-3 pages)

Reuse from M8-05. Include:

  • Slack adapter architecture
  • Job queue
  • Worker design
  • MCP Gateway
  • Multi-tenant in each layer
  • Failure handling

Section 7: Scaling Strategy (1-2 pages)

Adapted from M3 + M8-06. Include:

  • Capacity planning by month
  • Auto-scaling configs
  • Bottleneck analysis
  • Costs by scale

Section 8: Reliability Design (1-2 pages)

Adapted from M5 + M8-06. Include:

  • Tier 1/2/3 reliability patterns priorities
  • Monitoring & alerts
  • Disaster recovery scenarios
  • Runbook samples

Section 9: Architecture Decisions (6-8 ADRs, ~10 pages)

Use template from M7-07 applied to specific Capstone decisions:

  1. ADR-001: LLM Provider Strategy
  2. ADR-002: Vector Database
  3. ADR-003: Hosting Paradigm
  4. ADR-004: Agent Framework
  5. ADR-005: Channel Platform (Slack/Discord)
  6. ADR-006: Multi-tenant Approach
  7. (optional) ADR-007: Caching Strategy
  8. (optional) ADR-008: Embedding Model

Each ADR full template with context, options, criteria, scores, decision, trade-offs, reconsider triggers.

Section 10: Cost Projection (2 pages)

Reuse from M8-07. Include:

  • Year 1 monthly breakdown by component
  • Year 2 monthly breakdown
  • Cost per query analysis
  • Revenue projection for context
  • Optimization opportunities (semantic cache, multi-provider, self-hosted)

Section 11: Implementation Checklist (3-4 pages)

Aquí agregás algo nuevo: el roadmap detallado de implementación.

## Implementation Checklist

### Sprint 1-2: Foundation (Weeks 1-2)

**Goal**: Slack adapter functional + basic LLM call

- [ ] Setup repos: api-service, worker-service, mcp-gateway, infra-iac
- [ ] PostgreSQL schema: installations, jobs, tenant_credentials
- [ ] Slack app creation, OAuth flow
- [ ] Slack adapter: events endpoint with signature verification
- [ ] Tenant lookup logic
- [ ] Basic FastAPI deployment to Cloud Run
- [ ] Simple LLM call (no RAG yet) returning canned response
- [ ] Test end-to-end: install bot in test workspace, get response

**Done when**: bot installed in test Slack, can respond "Hello world" to @mentions

### Sprint 3-4: RAG (Weeks 3-4)

**Goal**: RAG pipeline working with one tenant's knowledge base

- [ ] Document ingestion: parse Notion + GitHub markdown
- [ ] Chunking strategy implementation (structural + fallback)
- [ ] Embedding pipeline (OpenAI text-embedding-3-small)
- [ ] Pinecone setup, indexing
- [ ] Retrieval (dense + sparse hybrid)
- [ ] Reranking (cross-encoder)
- [ ] LLM call with retrieved context
- [ ] Citation extraction
- [ ] Quality eval set (50 queries, ground truth)

**Done when**: ask question, get answer with cited sources from test KB

### Sprint 5-6: Agent + MCP (Weeks 5-6)

**Goal**: Agent decides RAG vs MCP tools

- [ ] LangGraph state machine
- [ ] Tool definitions (search_kb, search_github, search_notion)
- [ ] MCP Gateway: tool routing
- [ ] Notion MCP server (basic implementation)
- [ ] GitHub MCP server
- [ ] Tenant-scoped credentials in MCP Gateway
- [ ] Multi-step reasoning for complex queries
- [ ] Self-correction with citation verification

**Done when**: agent answers query that requires combining KB + GitHub

### Sprint 7-8: Reliability + Production (Weeks 7-8)

**Goal**: Production-ready

- [ ] Queue-based processing (Redis Streams)
- [ ] Worker pool with auto-scaling
- [ ] Idempotency on events
- [ ] Rate limiting (per-channel)
- [ ] Retry with backoff
- [ ] Circuit breaker for OpenAI
- [ ] Health checks (deep)
- [ ] Monitoring: Prometheus + Datadog basic dashboard
- [ ] Alerts: PagerDuty integration
- [ ] Runbook documentation
- [ ] Load test (simulated 100 queries/min)

**Done when**: load test passes, monitoring shows clean metrics

### Sprint 9-12: Polish + Beta (Weeks 9-12)

**Goal**: Beta launch with first 5 tenants

- [ ] Multi-tenant testing (3 test workspaces)
- [ ] Block Kit responses with citations + feedback buttons
- [ ] Interactivity (button handlers)
- [ ] Admin panel (web UI) for installations
- [ ] Analytics dashboard for tenants
- [ ] Documentation: setup guide for new tenants
- [ ] Onboard first 5 pilot clients
- [ ] Collect feedback, iterate

**Done when**: 5 pilot tenants actively using, NPS > 30

### Sprint 13-16: Scale Preparation (Weeks 13-16)

**Goal**: Tier 2 reliability + readiness for scale

- [ ] Multi-provider LLM (Anthropic fallback)
- [ ] Graceful degradation patterns
- [ ] Cache strategy (semantic if justified)
- [ ] Linear MCP server
- [ ] PDF ingestion
- [ ] Improved monitoring dashboards
- [ ] On-call rotation setup
- [ ] Update documentation
- [ ] Marketing site + onboarding flow

**Done when**: ready to onboard 20 more tenants without operational strain

Section 12: Risks and Mitigations (1 page)

Reuse from M8-06 + M8-07. List 5-8 risks with:

  • Likelihood (low/medium/high)
  • Impact (low/medium/high)
  • Mitigation plan
  • Trigger for escalation

Section 13: Appendices

  • A: PostgreSQL schemas (DDL)
  • B: Slack app manifest YAML
  • C: OpenAPI spec for MCP Gateway
  • D: Sample Block Kit responses (with screenshots)
  • E: Eval set sample (anonymized)
  • F: Glossary (RAG, MCP, ADR, C4, etc.)
  • G: References to source documents (M1-M7 deliverables)

Working approach

Suggested order to produce this document:

Day 1 (3-4 hours)

  1. Setup file structure (15 min): create architecture-design.md with sections empty
  2. Executive Summary (45 min): write last after everything, but draft now
  3. System Overview (45 min): can be done before details
  4. C4 Diagrams (90 min): produce all 3 levels using your tool of choice

Day 2 (3-4 hours)

  1. Sections 4-6 (RAG, Agent, Integration) (90 min): copy/adapt from M8-03, 04, 05
  2. Sections 7-8 (Scaling + Reliability) (60 min): copy/adapt from M8-06 + M5-08
  3. Section 9 (ADRs) (90 min): write 6 minimum, full template each

Day 3 (2-3 hours)

  1. Section 10 (Cost) (45 min): tables and projections from M8-07
  2. Section 11 (Implementation Checklist) (60 min): the most important new content
  3. Section 12 (Risks) (30 min)
  4. Appendices (45 min): schemas, manifests, references
  5. Polish + Executive Summary final (30 min)

Total: ~8-10 hours for a portfolio-worthy document.

Quality criteria

A senior peer reviewing your document should:

  • Understand the system in 5 min (executive summary + C4 context diagram)
  • Be able to defend each major decision (ADRs)
  • See specific numbers for costs (no vague estimates)
  • Find specific patterns/technologies (not generic)
  • See clear implementation path (checklist with sprints)
  • Identify and accept the trade-offs you accepted

If a peer can ask the question and your document has the answer → working.

Portfolio value

This document is portfolio gold. Use it:

  • Resume bullet: "Designed architecture for AI-Powered Knowledge Assistant (Agentic RAG, Slack, MCP, multi-tenant), production-ready blueprint for implementation"
  • Interview talking point: "Let me walk you through this 30-page document I produced. Each decision has a Decision Matrix with trade-offs. Here's why I chose Pinecone over self-hosted at our scale..."
  • GitHub portfolio: publish as a repo (sanitized if needed). Shows ability to think + document.
  • Reference for future projects: the framework transfers to any system design challenge.

Evidence of success

You'll know you're done when:

  • ✅ Document is complete (no TODO markers, no "to be filled")
  • ✅ Total length 20-50 pages (not less, not more)
  • ✅ Diagrams clearly communicate (C4 levels with purposes)
  • ✅ ADRs all complete with trade-offs and reconsider triggers
  • ✅ Cost projection has specific numbers, not "~around $X"
  • ✅ Implementation checklist is actionable (you can execute it)
  • ✅ A peer could review and give constructive feedback
  • ✅ You yourself can implement following this doc without re-thinking architecture

Connection to the broader path

You completed the System Design & Scaling guide. Next steps in the AI Engineering Path:

  1. Guide #22: AI Ethics & Compliance — may add considerations to refine
  2. Capstone implementation: build the Knowledge Assistant using this blueprint
  3. Production deployment: launch with pilot clients

The document you produced persists. Six months from now, it'll be the reference your team uses. A year from now, it'll evolve with new decisions documented as additional ADRs. Two years from now, it'll be the case study you tell when interviewing for Senior Engineer / Tech Lead roles.

Module 8 completed — Path completed

You learned to think like a senior architect:

  • ✅ Architectural thinking applied to AI specifically (M1)
  • ✅ Architecture choices justified (M2)
  • ✅ Scaling strategies (M3)
  • ✅ Integration patterns including MCP (M4)
  • ✅ Reliability at scale (M5)
  • ✅ Real-world channels: Slack/Discord (M6)
  • ✅ Trade-off frameworks (M7)
  • ✅ Synthesizing into complete designs (M8)

This guide is complete. You're ready to build production AI systems.

Next path in the AI Engineering journey

Guide #22 — AI Ethics & Compliance is the final guide. It covers:

  • Bias and fairness in AI systems
  • Privacy and GDPR
  • EU AI Act and emerging regulations
  • Ethics checklist for production deployments

After that: implement the Capstone using this blueprint.

Resources

  1. Real Architecture Design Documents (examples) — for inspiration.
  2. Stripe's architecture decision history — public examples.
  3. Uber Engineering Blog — system designs at scale.
  4. Architecture Decision Records repo.
  5. The Software Architect Elevator — Gregor Hohpe book on communicating architecture.
← AnteriorStack decisions + cost projection