The following markdown represents a set of architecture rules based on SOLID principles, adapted for modern frontend development (e.g. Vue 3 + TypeScript).

The goal is to provide AI coding agents with a clear instruction set so they follow clean architecture patterns by default, without needing to be reminded on every prompt.

What's included:

# Frontend Architecture Guidelines — SOLID Principles

> Drop this file in your project root and your AI agent (Claude, Cursor, Windsurf) will follow clean architecture principles by default. SOLID adapted to real frontend: composables, services, views, and components.

> These instructions apply to all frontend work in this project.
> Follow them when generating, refactoring, or reviewing code.
> The goal is a codebase that is scalable, easy to iterate, and safe to hand off to any developer.

> **Framework scope:** Examples use Vue 3 + TypeScript (Composition API). For React, replace `composables` → `hooks`, `defineProps` → prop types, `provide/inject` → Context API. The principles apply equally.

---

## S — Single Responsibility Principle

Every module has one reason to exist and one reason to change.

**Layer separation (enforce strictly):**
- `models/` — data contracts and TypeScript interfaces only. No logic.
- `services/` — API communication only. One service per domain (`BillingAPI`, `AuthAPI`...).
- `composables/` — reactive state and business logic per domain. No direct API calls.
- `views/` — page-level components. Orchestrate composables and pass data down to components. No business logic, no direct API calls.
- `components/` — presentation only. Receive data via props, emit events. No business logic, no direct API calls.
- `utils/` — pure functions only. No side effects, no state.

**Rules:**
- If you need "and" to describe what a module does, split it.
- If a view or component exceeds 400 lines, propose a split before continuing. Also flag any file under 400 lines that has more than one clear responsibility.
- Views integrate composables — they never contain business logic directly.
- Composables delegate data fetching to services — they never call `fetch` directly.

---

## O — Open/Closed Principle

Code should be open for extension and closed for modification.

**Rules:**
- Shared utilities (fetch factories, loggers, formatters) must be configurable via parameters, not modified per use case.
- When adding a new service or API integration, extend existing abstractions — do not fork them.
- New error types must extend the base error class, not add new `catch` branches throughout the codebase.
- Prefer composition over modification: wrap, extend, or configure — don't rewrite.

**Example pattern:**
```ts
// Correct: extend the factory, don't fork it
const useAdminFetch = useCustomFetch('/api/admin')
const usePublicFetch = useCustomFetch('/api/public')

L — Liskov Substitution Principle

Subtypes must be substitutable for their base types without breaking the application.

Rules:

Example pattern:

<!-- Correct: wrapper forwards all native attributes -->
<template>
  <button v-bind="$attrs" :class="styles" @click="handleClick">
    <slot />
  </button>
</template>

<script setup>
defineOptions({ inheritAttrs: false })
</script>

I — Interface Segregation Principle

No module should depend on interfaces it does not use.

Rules:

Red flag: if a composable interface has more than 10 members, review whether it should be split.


D — Dependency Inversion Principle

High-level modules must not depend on low-level implementations.

Rules:

Example pattern:

// Wrong: direct dependency on implementation
const res = await fetch(`${import.meta.env.VITE_API_URL}/users`)

// Correct: depend on abstraction
const { apiUrl } = useUrl()
const res = await useCustomFetch(apiUrl)('/users')

// For testing: injectable service
export function useUser(userService = defaultUserService) {
  // composable logic using userService
}

General Rules for AI Agents

When generating or refactoring code in this project, always:

  1. Check the layer — is this logic in the right place? (service vs composable vs view vs component)
  2. Check the size — if a file exceeds 400 lines, propose a split before continuing. Also flag files with multiple responsibilities regardless of size.
  3. Check the types — any is never acceptable. If the type is unknown, create an interface.
  4. Check the interface — is the module exposing more than it needs to?
  5. Check the dependencies — is this module depending on a concrete implementation it shouldn't know about?
  6. Check substitutability — if this component wraps a native element or extends another component, does it forward attributes and maintain event contracts?

When in doubt, ask: "does this module have exactly one reason to change?"


Audit Checklist

Run this before marking any refactoring task as done:



### **Why SOLID and not a custom ruleset**

SOLID is a well-known, battle-tested framework that any developer joining the project will already understand. Using it as the instruction set reduces onboarding friction for both humans and agents.