Renaissance Architecture

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

**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?"

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ariadoss
• Source: ariadoss/superskills
• License: MIT

Install and usage instructions live in the source repository linked above.