renaissance-architecture

What this skill does

# Renaissance Architecture

Build genuinely new things. Not "X but for Y."

---

## Core Philosophy

The problem isn't modern tools. It's building **commentaries instead of creations**.

Medieval scholars wrote commentaries on Aristotle instead of new philosophy. We build Star Wars spin-offs instead of new sci-fi. We add AI to existing workflows instead of asking what workflows become possible.

**Renaissance architecture means:**
- First-principles thinking about WHAT to build
- Pragmatic choices about HOW to build it
- Creating new paradigms, not extending old ones
- Using modern tools to make genuinely new things possible

---

## Architecture Principles

### 1. Simplicity as Default, Complexity When Earned

**Start simple, add complexity when pain is measurable.**

| Start With | Move To | When |
|------------|---------|------|
| SQLite | Postgres | >10 concurrent writers, >100GB, need PostGIS/full-text |
| Single file | Multiple files | File exceeds ~500 LOC or has multiple responsibilities |
| Monolith | Services | Team can't work on same codebase, or genuine scale isolation needed |
| Static hosting | Server | Need auth, real-time, or server-side computation |
| Local state | Cloud sync | Multi-device is a real user need, not assumed |

**Not dogma, but defaults.** Violate with documented reasoning.

---

### 2. Framework Choices

**Use frameworks when they provide genuine leverage.**

| Framework | When to Use | When to Avoid |
|-----------|-------------|---------------|
| **Next.js** | Full-stack React apps, SSR matters, team knows it | Simple static sites, non-React teams |
| **Remix** | Data-heavy apps, progressive enhancement priority | Simple SPAs, unfamiliar teams |
| **Astro** | Content sites, partial hydration valuable | Highly interactive apps |
| **SvelteKit** | Smaller bundles critical, team willing to learn | Large existing React codebases |
| **Rails/Django** | Rapid CRUD apps, admin panels, proven patterns | Real-time heavy, team prefers JS |
| **FastAPI** | Python APIs, async matters | Simple scripts, team prefers other languages |
| **Hono/Elysia** | Edge functions, lightweight APIs | Complex apps needing full framework |

**The question isn't "framework or not" but "does this framework serve the thing we're creating, or are we creating something that serves the framework?"**

---

### 3. Human-Legible Systems

**Configuration**
- YAML/JSON are fine - the format isn't the problem
- Problem is: 500-line configs with nested conditionals
- Good: Config a new team member can read and modify in 10 minutes
- Document non-obvious settings inline

**Error messages that teach**
- What happened
- Why it happened
- What to do about it
- Link to docs if complex

**Logs you can understand**
- Structured logging (JSON) for machines
- Human-readable format for development
- Timestamps, context, severity
- Searchable without specialized tools

**Documentation lives WITH code**
- README in each significant directory
- API docs generated from code
- Architecture decisions recorded (ADRs)
- External wikis for onboarding/process only

---

### 4. Local-First Where It Matters

**Not "never use cloud" but "don't require cloud unnecessarily."**

| Feature | Local-First Approach | Cloud When |
|---------|---------------------|------------|
| Core functionality | Works offline | Never required for core |
| Data storage | SQLite/local storage | Sync, backup, multi-device |
| Computation | Client-side where possible | Heavy processing, shared resources |
| Auth | Local sessions work | OAuth for third-party, enterprise SSO |

**State should be inspectable**
- Serialize state to file for debugging
- State machines explicit, not implicit
- Reproducible from snapshot

**Sync as enhancement**
- Local is source of truth where possible
- Sync failures don't break the app
- Conflict resolution explicit, user-controlled

---

### 5. Composition Mindset

**Libraries over frameworks when:**
- You need one capability, not an ecosystem
- You want to control the architecture
- Exit cost matters more than speed

**Frameworks over libraries when:**
- Team expertise exists
- Time-to-market critical
- Convention over configuration is valuable
- The framework's opinions align with your needs

**APIs expose primitives**
- Convenience methods are fine
- But power users can access lower levels
- Don't hide the machine

**Minimize exit costs**
- Data exportable in standard formats
- Avoid proprietary lock-in where practical
- Document the exit path even if you never use it

---

## Cloud & Infrastructure

### When Cloud Makes Sense

| Use Case | Cloud Appropriate | Local/Edge Better |
|----------|-------------------|-------------------|
| Auth | Enterprise SSO, OAuth providers | Simple username/password |
| Storage | Multi-device sync, collaboration | Single-user, offline-capable |
| Compute | Heavy ML inference, video processing | Text processing, simple transforms |
| Database | Multi-writer, global distribution | Single user, local-first |
| Real-time | Multi-user collaboration | Single-user state |

### Cloud Pragmatically

- **Serverless** for spiky, unpredictable loads
- **Edge functions** for latency-sensitive operations
- **Managed databases** when ops overhead > cost
- **Self-hosted** when control/cost/compliance require it

**The question: Does cloud serve your users, or does it serve your assumptions about scale you don't have?**

---

## UI/UX Philosophy

### 1. Immediate Feedback

**<100ms for user actions, honest progress for longer operations**

- Optimistic updates where safe (can rollback)
- Progress indicators that reflect actual work
- Spinners are fine - they indicate honest work
- Skeleton screens for predictable loading patterns

**Loading states should:**
- Show what's happening
- Estimate time when possible
- Allow cancellation for long operations
- Never fake progress

---

### 2. Visible State

**User always knows what the system is doing**

- Status visible without digging
- Background processes surfaced
- Errors prominent, not hidden
- System explains its decisions when non-obvious

**No black boxes**
- User can understand why something happened
- Audit trail for important actions
- State inspectable in dev tools

---

### 3. Spatial Consistency

**Things stay where you put them**

- No layout shifts after load
- No rearranging "for the user"
- Muscle memory works
- Consistent component placement

**Predictable navigation**
- Back button works
- URLs are bookmarkable and shareable
- State survives refresh
- Deep linking works

---

### 4. Undo & Recovery

**Implemented at the data layer, not just UI**

- Soft delete by default
- Versioned state where valuable
- Recovery path documented
- "Are you sure?" is not a substitute for undo

**Destructive actions**
- Confirmation for irreversible operations
- Grace period before permanent deletion
- Clear communication of consequences

---

### 5. Respect Attention

**Notifications**
- User opts in explicitly
- Meaningful, not engagement-driven
- Batched where appropriate
- Easy to adjust or disable

**Modals & Interruptions**
- User-initiated, not system-initiated
- Dismissable
- Don't trap focus unnecessarily
- Keyboard accessible

**Autoplay**
- Never for audio
- Video only with explicit user intent
- Motion respects prefers-reduced-motion

**Defaults over customization**
- Good defaults eliminate settings
- Power user options available but not required
- Complexity progressive

---

## What This Rejects

### Derivative Thinking
- "X but for Y" without asking if Y needs X
- Features because competitors have them
- Patterns because tutorials use them
- Architecture because FAANG does it

### Cargo Cult Engineering
- "Best practices" from different-scale companies
- Microservices for 3-person teams
- Kubernetes for single-server loads
- OAuth for internal tools

### Premature Complexity
- Abstraction layers "for future flexibility"
- Scale architecture before scale problems
- Features before foundations