Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
277 lines (189 loc) · 8.82 KB

ARCHITECTURE.md

File metadata and controls

277 lines (189 loc) · 8.82 KB

Content Engine - Architecture Decisions

For Loom Video / Interview Prep

This document explains the key architectural decisions made while building Content Engine, what I (Austin) decided versus what AI (Claude Code) handled, and why those choices demonstrate AI-first development principles.

Core Principle: AI as Force Multiplier

My Role: Architect, validator, decision-maker AI's Role: Executor, synthesizer, implementation partner Result: 10x faster than traditional development

Key Architectural Decisions (What I Decided)

1. Python Over TypeScript

Decision: Rebuild from TypeScript to Python Why: Better AI/ML ecosystem (LangChain, LlamaIndex, Anthropic SDK) AI's Role: Handled the migration, rewrote all code My Role: Validated correctness, ensured patterns matched

Demonstrates: Strategic technology choices based on long-term goals

2. SQLite for MVP, PostgreSQL for Scale

Decision: Start with SQLite, design for PostgreSQL migration Why:

  • SQLite = zero ops, single file, perfect for MVP
  • SQLAlchemy ORM = swap to PostgreSQL with 1 line change
  • Don't optimize prematurely

AI's Role: Implemented SQLAlchemy models My Role: Chose the abstraction layer (ORM vs raw SQL)

Demonstrates: Pragmatic architecture (start simple, scale when needed)

3. CLI-First, UI Later

Decision: Build CLI before web UI Why:

  • Faster to build (4 hours vs 2 days)
  • Interview demo ready sooner
  • Actually useful to me right now
  • UI can come in Phase 2

AI's Role: Implemented Click CLI commands My Role: Designed the UX (command names, options, workflows)

Demonstrates: MVP thinking (ship what's valuable first)

4. Database-Backed OAuth (Not Just .env)

Decision: Store OAuth tokens in database, not just environment variables Why:

  • .env = manual, expires, single-user
  • Database = refreshable, multi-user ready, persistent
  • Prepares for scaling

AI's Role: Created OAuthToken model, migration script My Role: Designed the schema, decided what to store

Demonstrates: Forward-thinking (build for tomorrow, not just today)

5. Status-Based Workflow (draft → approved → posted)

Decision: Posts flow through states (draft, scheduled, posted, failed) Why:

  • Human-in-the-loop (I approve before posting)
  • Audit trail (what was posted when)
  • Error recovery (failed posts can be retried)

AI's Role: Implemented PostStatus enum, state transitions My Role: Designed the workflow, state machine logic

Demonstrates: Production thinking (systems need observability and control)

6. Background Worker for Scheduled Posts

Decision: Separate worker process (not in-app scheduler) Why:

  • Decoupled (worker can restart independently)
  • Cron-compatible (standard ops tooling)
  • Easier to monitor and debug

AI's Role: Wrote worker.py, cron integration My Role: Chose the architecture (separate process vs in-app)

Demonstrates: Systems thinking (separation of concerns)

7. Error Handling with Custom Exceptions

Decision: Custom exception types (LinkedInAPIError, OAuthError, ConfigurationError) Why:

  • Better debugging (specific error types)
  • Cleaner error handling (catch specific exceptions)
  • Production-ready (no generic "Exception" catching)

AI's Role: Implemented custom exception classes My Role: Defined the exception hierarchy

Demonstrates: Code quality (thoughtful error handling)

8. Structured Logging Throughout

Decision: Consistent logging in all modules Why:

  • Debugging (see what's happening)
  • Production observability (monitor in deployment)
  • Interview demo (shows professional practices)

AI's Role: Added logging to all functions My Role: Decided logging strategy (what to log, at what level)

Demonstrates: Production mindset (observability from day 1)

9. Testing from the Start

Decision: Write tests as we build (not after) Why:

  • Faster iteration (catch bugs immediately)
  • Refactoring confidence (tests validate changes)
  • Interview proof (shows engineering rigor)

AI's Role: Wrote test cases, implemented pytest My Role: Decided what to test, coverage requirements

Demonstrates: Engineering discipline (test-driven mindset)

10. Monorepo Structure (agents, lib, tests, scripts)

Decision: Organized code into logical modules Why:

  • agents/ = platform-specific code (LinkedIn, Twitter)
  • lib/ = shared utilities (config, errors, logging, database)
  • tests/ = validation
  • scripts/ = ops tools (deploy, migrate)

AI's Role: Created files in correct locations My Role: Designed the folder structure

Demonstrates: Code organization (maintainable from the start)

What AI Handled (Implementation)

  1. OAuth 2.0 Flow: Complete implementation (server, token exchange, user info)
  2. SQLAlchemy Models: Database schema, relationships, queries
  3. Click CLI: All commands, argument parsing, help text
  4. Error Handling: Try/catch blocks, custom exceptions, logging
  5. Worker Logic: Scheduled post processing, database queries
  6. Tests: Test cases, assertions, mocking
  7. Deployment Script: rsync, SSH commands, server setup
  8. Documentation: README, docstrings, type hints

Why this matters: I didn't write 90% of the code by hand. I directed, validated, and iterated.

What I Validated (Quality Assurance)

  1. Code Quality: Reviewed all AI-generated code before committing
  2. Architecture: Ensured patterns matched my design intent
  3. Error Cases: Validated edge cases were handled
  4. Security: No credentials in code, proper OAuth flow
  5. Performance: Database queries are efficient, no N+1 problems
  6. UX: CLI commands are intuitive, help text is clear
  7. Tests: Verified tests actually validate behavior

Why this matters: AI accelerates, but humans validate. This is AI-first, not AI-only.

Time Breakdown (8 Hours Total)

Phase Time What I Did What AI Did
Phase 1 2 hours Designed OAuth flow, directed architecture Implemented OAuth server, posting agent
Phase 1.5 4 hours Designed database schema, CLI UX, worker logic Implemented models, CLI, worker, migration
Testing 1 hour Defined test cases, validated behavior Wrote test code, ran pytest
Documentation 1 hour Outlined README structure, architecture docs Wrote detailed docs, examples

Traditional Development: 2-3 days (16-24 hours) AI-First Development: 8 hours Speedup: 2-3x

How This Applies to Vixxo (Or Any Company)

The Pattern:

  1. I understand the business problem (what needs to be automated)
  2. I design the solution architecture (how to solve it)
  3. AI handles implementation (writes the code)
  4. I validate and iterate (ensure quality, correctness)
  5. We ship 2-3x faster (than traditional development)

This is what I'd teach your teams:

  • Don't write boilerplate by hand (OAuth flows, database models, CLI parsers)
  • Do design the architecture (what problems to solve, how to solve them)
  • Validate everything (AI is fast, humans ensure correctness)
  • Iterate in real-time (AI can refactor instantly, try multiple approaches)

Example at Vixxo:

"Your ops team needs to automate equipment status reporting. I'd:

  1. Interview ops team (understand workflow, pain points)
  2. Design the system (database schema, API endpoints, notification triggers)
  3. Use AI to build it (implement models, endpoints, workers)
  4. Validate with ops team (does it solve the problem?)
  5. Ship in days, not weeks"

Loom Video Talking Points

Opening:

  • "I built Content Engine in 8 hours using AI-first development"
  • "This is the same approach I'd teach your teams"

Architecture Decisions:

  • Walk through 2-3 key decisions (Python choice, CLI-first, database-backed OAuth)
  • Explain: "I decided the architecture, AI implemented it, I validated"

Code Demo:

  • Show CLI in action (draft → approve → post)
  • Explain: "AI wrote this CLI in 30 minutes, I designed the UX"

Interview Connection:

  • "This is how I'd help Vixxo teams work AI-first"
  • "Design → AI implements → Validate → Ship fast"

Bottom Line

Content Engine demonstrates:

  • ✅ AI-first development (2-3x faster than traditional)
  • ✅ Production architecture (error handling, logging, testing, deployment)
  • ✅ System design thinking (database, CLI, workers, separation of concerns)
  • ✅ Teaching ability (this document explains my thought process clearly)

This is the exact skillset Vixxo is looking for:

  • Build with AI as force multiplier
  • Teach teams to work this way
  • Deliver faster, higher quality systems
  • Transform how work gets done

Built with Claude Code in 8 hours. Traditional development: 2-3 days.

That's the power of AI-first engineering.