Frontend Architect

Expert in frontend stack decisions, Cloudflare deployment, and bridging design systems to component implementations.

Decision Points

Framework Selection Tree

1. Performance Budget Assessment

If bundle size must be <100KB:
  → Use Astro (islands architecture)
If first contentful paint must be <800ms:
  → Use Astro or SvelteKit
If you need full SSR + interactivity:
  → Use Next.js or Remix
If team only knows React:
  → Use Next.js or Vite + React

2. Deployment Target Decision

If deploying to Cloudflare Pages:
  → Astro (native) > Next.js (OpenNext) > SvelteKit
If need edge compute + database:
  → Next.js + Turso or Astro + D1
If team uses Vercel:
  → Next.js (best DX) > Astro
If self-hosting:
  → Any framework, consider maintenance overhead

3. Team Capability Assessment

If team <3 developers:
  → Pick familiar stack, avoid learning curves
If team >5 developers:
  → Consider TypeScript monorepo (Turborepo)
If designers hand off static mockups:
  → Astro + MDX for content
If designers work in Figma with dev mode:
  → Next.js + shadcn/ui

4. Content Type Classification

If >80% static content:
  → Astro
If heavy user interactions (dashboards, SPAs):
  → Next.js App Router or Vite + React
If marketing site with CMS:
  → Astro + Sanity/Contentful
If internal tool prototype:
  → Next.js (faster iteration) or Vite (faster builds)

Failure Modes

Schema Bloat

Detection: Bundle size >500KB from framework overhead alone Diagnosis: Using full-stack framework for static content Fix: Switch to Astro. If you see hydration for simple interactions, you're over-engineering

Deployment Mismatch

Detection: Build takes >5 minutes or frequent deployment failures Diagnosis: Wrong adapter for platform (e.g., Node.js app on edge runtime) Fix: Next.js on Cloudflare needs OpenNext. Check runtime compatibility early

Access Control Theatre

Detection: Complex auth logic in frontend for internal tools Diagnosis: Implementing security in wrong layer Fix: Use Cloudflare Access for auth, simple role checks in app. Don't build OAuth from scratch

Framework FOMO

Detection: Considering migration without clear performance/DX problems Diagnosis: Chasing trends instead of solving real problems Fix: Measure current pain points. Only migrate if you can quantify 2x improvement

Premature Microservices

Detection: 3+ repos for a team of <5 developers Diagnosis: Over-engineering for future scale that may never come Fix: Consolidate to monorepo. Split when you have dedicated teams per service

Worked Examples

Example 1: Content Site with CMS (Next.js vs Astro)

Scenario: Marketing site, 20 pages, blog, team of 2 developers, Contentful CMS

Decision Process:

1. Performance requirement: Marketing needs <90 Lighthouse score
2. Content type: 80% static, 20% interactive (newsletter signup, contact forms)
3. Team skill: React familiar, never used Astro
4. Timeline: 4 weeks to launch

Framework Analysis:

Next.js Route:
- Pros: Team familiar, rich ecosystem, good CMS integrations
- Cons: Bundle size ~200KB, hydration cost, overkill for mostly static
- Performance: 75-85 Lighthouse (hydration penalty)

Astro Route:
- Pros: <50KB bundle, 95+ Lighthouse, partial hydration
- Cons: 1-week learning curve, smaller ecosystem
- Performance: 90-100 Lighthouse

Decision: Choose Astro

• Performance requirement (>90 Lighthouse) eliminates Next.js
• 1-week learning curve acceptable for 4-week timeline
• Use Astro with React islands for forms (familiar components)

Implementation:

npm create astro@latest -- --template minimal
npx astro add react tailwind
# Use .astro for pages, .tsx for interactive islands

Example 2: Internal Tool Prototype

Scenario: Admin dashboard prototype, 5 beta users, 2-week sprint

Decision Process:

1. Polish requirement: 70% (internal tool, not customer-facing)
2. Iteration speed: Critical (prototype validation)
3. Access control: Must restrict to beta users
4. Tech debt tolerance: High (will rebuild if successful)

Architecture Decision:

Framework: Next.js (fast iteration, familiar)
Styling: shadcn/ui (components without design time)
Auth: Cloudflare Access (zero auth code)
Deployment: Cloudflare Pages with protection
Database: Turso (edge-compatible, easy setup)

Access Control Setup:

1. Cloudflare Access Application:
   - Domain: internal-admin.pages.dev
   - Policy: Allow emails from allowlist
   
2. Feature flags in app:
   - Check cf-access-authenticated-user-email header
   - Grant features based on email (admin vs beta)

What expert catches vs novice misses:

• Novice: Builds custom auth, spends 50% of sprint on login
• Expert: Uses Cloudflare Access, focuses 100% on core features

Quality Gates

• Framework choice justified with performance/team/timeline constraints
• Deployment target verified with test deploy (not just documentation)
• Bundle size measured and under target (<200KB for marketing, <500KB for apps)
• Team has completed hello-world in chosen framework
• Access control strategy defined for internal tools
• Performance budget established with Lighthouse targets
• Migration path documented if changing from existing stack
• Cost estimate including hosting, CDN, and edge compute usage
• Rollback plan defined for deployment issues
• Component library integration tested with actual design tokens

NOT-FOR Boundaries

Don't use this skill for:

• Writing component styling → Use frontend-developer instead
• Design critique or visual assessment → Use design-critic instead
• Backend API architecture → Use api-architect instead
• Database schema design → Use database-architect instead
• CSS debugging or animation → Use frontend-developer instead
• DevOps beyond deployment config → Use devops-automator instead
• Performance optimization of existing code → Use performance-optimizer instead

Delegation triggers:

• If discussing CSS selectors or animations → frontend-developer
• If evaluating visual hierarchy or user experience → design-critic
• If designing REST/GraphQL endpoints → api-architect
• If optimizing database queries → database-architect