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.
# 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')
Subtypes must be substitutable for their base types without breaking the application.
Rules:
button, input, a...), it must forward all standard HTML attributes using v-bind="$attrs". Consumers should not need to know they are using a wrapper.IconButton, AdminUserCard) must be drop-in replacements for their base (BaseButton, UserCard) without breaking the parent's layout or event expectations.BaseInput emits update:modelValue, SearchInput must emit the same event with the same payload type.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>
No module should depend on interfaces it does not use.
Rules:
CreateUserPayload, UpdateUserPayload, DeleteUserPayload — never UserPayload with all optional fields.defineProps<{...}>. Only declare props the component actually uses.Red flag: if a composable interface has more than 10 members, review whether it should be split.
High-level modules must not depend on low-level implementations.
Rules:
fetch directly — they depend on a configurable fetch abstraction.import.meta.env directly — environment variables are consumed through a dedicated config abstraction (useUrl, useConfig, or similar).provide/inject over direct cross-composable imports when composables need to share state.utils/ and models/ must never import framework-specific code (ref, reactive, useState...). They must be pure TypeScript, framework-agnostic, and independently testable.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
}
When generating or refactoring code in this project, always:
any is never acceptable. If the type is unknown, create an interface.When in doubt, ask: "does this module have exactly one reason to change?"
Run this before marking any refactoring task as done:
any in TypeScriptfetch calls outside service layerimport.meta.env reads outside config abstractiondefineProps<{...}>v-bind="$attrs" and inheritAttrs: falseutils/ and models/ contain no framework-specific imports
### **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.