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 work
- Real-time before single-user works
Process Over Thinking
- Scrum ceremonies replacing actual thought
- Documentation for compliance, not clarity
- Meetings about meetings
- Roadmaps pretending to predict
---
Application
When Reviewing Designs
First-Principles Check
- [ ] What new thing does this create? (Not "what existing thing does it extend?")
- [ ] Why does this need to exist?
- [ ] What becomes possible that wasn't before?
Simplicity Check
- [ ] Is complexity earned or assumed?
- [ ] Can a new developer understand this in an hour?
- [ ] What's the simplest version that solves the core problem?
Tool Fitness Check
- [ ] Do tool choices serve the creation, or does creation serve the tools?
- [ ] Is the framework justified by team expertise + problem fit?
- [ ] Are cloud dependencies necessary or assumed?
Human-Legibility Check
- [ ] Can someone read the config and understand it?
- [ ] Do error messages teach?
- [ ] Is documentation where developers will find it?
UI/UX Check
- [ ] Is feedback immediate or honestly progressive?
- [ ] Can users see what the system is doing?
- [ ] Is everything recoverable/undoable?
- [ ] Are interruptions user-initiated?
---
When Generating Solutions
Start by asking:
- What genuinely new thing are we creating?
- What's the simplest architecture that enables it?
- What complexity is earned by real constraints?
Default to:
- Simplest tool that works
- Framework if team knows it and it fits
- Local-first where possible
- Cloud where genuinely needed
Add complexity when:
- Pain is measurable, not theoretical
- Team agrees on the tradeoff
- The path back to simple is documented
---
Threshold Triggers
When to upgrade from defaults:
| From | To | Trigger |
|---|---|---|
| SQLite | Postgres | >10 concurrent writers OR >100GB data OR need PostGIS/full-text search |
| Monolith | Services | Team can't work on same codebase OR genuine scale isolation needed |
| Static | Server | Need auth, real-time, or server-side computation |
| Local storage | Cloud sync | Multi-device is validated user need, not assumption |
| Library | Framework | Team expertise exists AND time-to-market critical AND framework opinions align |
| Simple | Complex | Pain is measurable, not theoretical |
---
Justified Exceptions
Complexity is acceptable when:
- Frameworks: Team expertise exists AND problem fits framework opinions AND time-to-market matters
- Cloud dependencies: Multi-user collaboration OR heavy compute OR compliance requires it
- Microservices: Teams can't coordinate on monolith OR genuine scale isolation needed
- Heavy tooling: Build time investment pays off in development velocity
Document the reasoning. Future you will thank present you.
---
Pragmatic Defaults
Start simple, add complexity when pain is measurable.
- Begin with the simplest architecture that could work
- Wait for real problems, not imagined ones
- Measure before optimizing
- Document why you're adding complexity
- Ensure the path back to simple exists
Premature complexity is technical debt with interest.
---
Anti-Dogma Clause
These are defaults, not laws. Violate with documented reasoning.
Every principle here has valid exceptions. The goal isn't purity - it's intentionality.
Valid reasons to deviate:
- Team expertise strongly favors different approach
- Business timeline requires faster path
- Regulatory/compliance requirements
- Measured performance needs
- User research contradicts assumption
Invalid reasons to deviate:
- "Everyone does it this way"
- "We might need it someday"
- "The tutorial used this"
- "It's best practice" (without understanding why)
When you deviate, write down why. One sentence in a comment, ADR, or README.
---
Quick Reference
| Dimension | Default | Upgrade When |
|---|---|---|
| Storage | SQLite | Concurrent writes, scale, features |
| Framework | Yes, if team knows it | Build from scratch if simpler |
| Cloud | Where genuinely needed | Don't assume, validate |
| Config | YAML/JSON, well-documented | - |
| Errors | Teaching messages | - |
| Loading | Spinners with honest progress | - |
| State | Visible, inspectable | - |
| Undo | Data-layer versioning | - |
| Complexity | Earned, not assumed | Document reasoning |
---
The Core Question
When designing anything, ask:
"Am I creating something new, or commenting on something that exists?"
Renaissance architecture isn't about rejecting modern tools. It's about using them to build genuinely new things - not just another variation on established patterns.
Medieval scholars could only write commentaries because they believed truth was revealed in the past. We have no such limitation. We can create.
