| name | renaissance-architecture |
| description | Software architecture and UI/UX principles for building genuinely new solutions, not derivative work. Use when designing features, architecting software, brainstorming apps, reviewing designs, or during strategy discussions. Focuses on first-principles thinking, simplicity where it matters, and creating rather than commenting. |
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
| 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
- 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
Documentation lives WITH code
- README in each significant directory
- API docs generated from code
- Architecture decisions recorded (ADRs)
4. Local-First Where It Matters
| 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 |
Sync as enhancement — local is source of truth where possible. Conflict resolution explicit, user-controlled.
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
- 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
3. Spatial Consistency
Things stay where you put them
- No layout shifts after load
- No rearranging "for the user"
- Muscle memory works
- Back button works, URLs are bookmarkable
4. Undo & Recovery
Implemented at the data layer, not just UI
- Soft delete by default
- Versioned state where valuable
- "Are you sure?" is not a substitute for undo
- Clear communication of consequences for destructive actions
5. Respect Attention
- Notifications: user opts in explicitly, meaningful, easy to disable
- Modals: user-initiated, dismissable
- Autoplay: never for audio, motion respects prefers-reduced-motion
- Good defaults eliminate settings
What This Rejects
Derivative Thinking
- "X but for Y" without asking if Y needs X
- Features because competitors have them
- Architecture because FAANG does it
Cargo Cult Engineering
- 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
Application
When Reviewing Designs
Threshold Triggers
| 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 |
Anti-Dogma Clause
These are defaults, not laws. Violate with documented reasoning.
Valid reasons to deviate: team expertise, business timeline, regulatory/compliance requirements, measured performance needs, user research that contradicts assumptions.
When you deviate, write down why. One sentence in a comment, ADR, or README.
The Core Question
When designing anything, ask:
"Am I creating something new, or commenting on something that exists?"
