Frontend Project Architecture Design

🎯 Core Question

How do you choose the right architecture for projects of different sizes, from simple HTML pages to complex enterprise applications? It's like asking: from a studio apartment to a large shopping mall, how do you design different spatial layouts based on needs? Good architecture should evolve with the project, rather than being over-engineered from the start.

1. Architecture Evolution: From Simple to Complex

1.1 Three Complexity Levels Overview

Frontend project architecture should match project complexity. We classify projects into three levels based on technical complexity and user scale:

Level	Tech Stack	User Scale	Typical Scenarios	Core Focus
Beginner	HTML/CSS/JS	Individual/small team	Personal blogs, landing pages, simple tools	Quick launch, simple maintenance
Intermediate	Vue/React + build tools	Small-to-medium business	Management systems, e-commerce frontends, SaaS	Component reuse, state management
Enterprise	Framework + micro-frontend/SSR	Large applications	Large platforms, complex business systems	Performance optimization, team collaboration, scalability

💡 How to Choose?

Don't over-engineer! Many projects start with simple HTML and gradually introduce frameworks and tools as needs grow.

Personal projects → Beginner level
Startup MVP → Beginner or intermediate level
Enterprise management systems → Intermediate level
Large internet platforms → Enterprise level

2. Beginner Level: HTML/CSS/JS Projects

2.1 Suitable Scenarios

Personal blogs, resume pages
Product landing pages
Simple tool pages (calculators, converters, etc.)
Prototype validation, quick demos

2.2 Recommended Directory Structure

my-simple-project/
├── index.html              # Homepage
├── about.html              # About page (if needed)
├── css/
│   ├── reset.css           # Reset styles
│   ├── variables.css       # CSS variables (colors, fonts, etc.)
│   ├── components.css      # Component styles (buttons, cards, etc.)
│   └── main.css            # Main stylesheet
├── js/
│   ├── utils.js            # Utility functions
│   ├── api.js              # Simple API calls
│   └── main.js             # Main logic
├── assets/
│   ├── images/             # Image assets
│   └── fonts/              # Font files
└── README.md               # Project documentation

2.3 Code Organization Principles

HTML: Semantic tags, clear structure

html

<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Personal Blog</title>
  <link rel="stylesheet" href="css/reset.css">
  <link rel="stylesheet" href="css/variables.css">
  <link rel="stylesheet" href="css/components.css">
  <link rel="stylesheet" href="css/main.css">
</head>
<body>
  <header class="site-header">
    <nav class="main-nav">
      <a href="index.html">Home</a>
      <a href="about.html">About</a>
    </nav>
  </header>

  <main class="content">
    <article class="blog-post">
      <h1>Article Title</h1>
      <p>Article content...</p>
    </article>
  </main>

  <footer class="site-footer">
    <p>&copy; 2024 My Blog</p>
  </footer>

  <script src="js/utils.js"></script>
  <script src="js/main.js"></script>
</body>
</html>

CSS: Use CSS variables to manage themes

css

/* variables.css */
:root {
  --primary-color: #3498db;
  --text-color: #333;
  --bg-color: #fff;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
  --font-base: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}

/* components.css - Reusable component styles */
.btn {
  padding: var(--spacing-sm) var(--spacing-md);
  border: none;
  border-radius: 4px;
  background: var(--primary-color);
  color: white;
  cursor: pointer;
}

.card {
  padding: var(--spacing-md);
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0,0,0,0.1);
}

JavaScript: Modular organization (using ES6 modules or simple splitting)

javascript

// utils.js
const utils = {
  // Simplified DOM operations
  $(selector) {
    return document.querySelector(selector);
  },

  // Simple debounce
  debounce(fn, delay) {
    let timer;
    return function(...args) {
      clearTimeout(timer);
      timer = setTimeout(() => fn.apply(this, args), delay);
    };
  },

  // Local storage wrapper
  storage: {
    get(key) {
      return JSON.parse(localStorage.getItem(key) || 'null');
    },
    set(key, value) {
      localStorage.setItem(key, JSON.stringify(value));
    }
  }
};

// main.js
document.addEventListener('DOMContentLoaded', () => {
  // Page initialization logic
  initNavigation();
  loadBlogPosts();
});

2.4 Best Practices

✅ Do:

Use semantic HTML tags
Use CSS variables for colors and spacing
Compress and lazy-load images
Add basic SEO meta tags

❌ Avoid:

Inline styles (style="...")
Global variable pollution
Duplicate code (copy-paste)

3. Intermediate Level: Vue/React Framework Projects

3.1 Suitable Scenarios

Enterprise management systems (ERP, CRM, OA)
E-commerce frontends/backends
SaaS applications
Web applications requiring complex interactions

3.2 Vue Project Recommended Structure

my-vue-project/
├── public/                     # Static assets
│   ├── index.html
│   └── favicon.ico
├── src/
│   ├── assets/                 # Styles, images, fonts
│   │   ├── styles/
│   │   │   ├── variables.scss
│   │   │   ├── mixins.scss
│   │   │   └── global.scss
│   │   └── images/
│   ├── components/             # Shared components
│   │   ├── common/             # Global shared (Button, Modal, etc.)
│   │   │   ├── Button/
│   │   │   │   ├── index.vue
│   │   │   │   └── Button.scss
│   │   │   └── Modal/
│   │   └── business/           # Business components (UserCard, etc.)
│   ├── views/                  # Page components
│   │   ├── Home/
│   │   ├── User/
│   │   │   ├── List.vue
│   │   │   └── Detail.vue
│   │   └── Product/
│   ├── router/                 # Route configuration
│   │   └── index.js
│   ├── stores/                 # Pinia/Vuex state management
│   │   ├── user.js
│   │   └── app.js
│   ├── services/               # API services
│   │   ├── request.js          # axios wrapper
│   │   ├── user.js
│   │   └── product.js
│   ├── utils/                  # Utility functions
│   │   ├── format.js
│   │   ├── validate.js
│   │   └── storage.js
│   ├── composables/            # Composable functions
│   │   ├── useAuth.js
│   │   └── useLoading.js
│   ├── constants/              # Constant definitions
│   │   └── index.js
│   ├── App.vue
│   └── main.js
├── tests/                      # Test files
├── .env                        # Environment variables
├── vite.config.js
├── package.json
└── README.md

3.3 React Project Recommended Structure

my-react-project/
├── public/
├── src/
│   ├── assets/
│   ├── components/
│   │   ├── common/             # Shared components
│   │   │   ├── Button/
│   │   │   │   ├── index.jsx
│   │   │   │   └── Button.module.css
│   │   │   └── Modal/
│   │   └── business/           # Business components
│   ├── pages/                  # Page components
│   │   ├── Home/
│   │   ├── User/
│   │   └── Product/
│   ├── hooks/                  # Custom Hooks
│   │   ├── useAuth.js
│   │   └── useFetch.js
│   ├── services/               # API services
│   │   ├── api.js
│   │   └── userService.js
│   ├── store/                  # Redux/Zustand state management
│   │   ├── slices/
│   │   └── index.js
│   ├── utils/
│   ├── constants/
│   ├── App.jsx
│   └── main.jsx
├── tests/
└── package.json

3.4 Key Concepts Explained

Component Design Principles

Single Responsibility: One component does one thing

vue

<!-- ❌ Bad example: Component does too much -->
<template>
  <div>
    <form @submit="handleSubmit">
      <!-- Form content -->
    </form>
    <table>
      <!-- Data table -->
    </table>
    <div class="charts">
      <!-- Charts -->
    </div>
  </div>
</template>

<!-- ✅ Good example: Split into independent components -->
<template>
  <div>
    <UserForm @submit="fetchData" />
    <UserTable :data="users" />
    <UserStats :data="users" />
  </div>
</template>

State Management Strategy

State Type	Storage Location	Example
Global state	Pinia/Redux	User info, login status, theme settings
Page state	Page component	List query conditions, pagination info
Component state	Component internal	Form inputs, modal show/hide
Server state	TanStack Query/SWR	Server data, caching

Directory Organization Approach Selection

Approach 1: Organize by type (suitable for small projects)

src/
├── components/     # All components
├── views/          # All pages
├── stores/         # All state
└── services/       # All services

Approach 2: Organize by feature (suitable for medium-to-large projects)

src/
├── features/
│   ├── auth/       # All code for authentication feature
│   ├── user/       # All code for user feature
│   └── product/    # All code for product feature
├── shared/         # Shared resources
└── App.vue

💡 How to Choose?

Project pages < 10 → Organize by type
Project pages > 20 → Organize by feature
Team > 5 people → Organize by feature for parallel development

4. Enterprise Level: Large Application Architecture

4.1 Suitable Scenarios

Large internet platforms (e-commerce, social, content platforms)
Complex enterprise applications
Projects requiring multi-team collaboration
Projects with extremely high performance and maintainability requirements

4.2 Micro-Frontend Architecture

When a project grows to a certain size and a single codebase becomes difficult to maintain, micro-frontend architecture can be considered.

Large E-Commerce Platform/
├── Base Application (Main Framework)
│   ├── Top Navigation
│   ├── Side Menu
│   ├── User Center Entry
│   └── Sub-application Container
├── Product Sub-application (Independently deployed)
│   ├── Product List
│   ├── Product Details
│   └── Product Management
├── Order Sub-application (Independently deployed)
│   ├── Shopping Cart
│   ├── Order List
│   └── Payment Flow
├── User Sub-application (Independently deployed)
│   ├── Personal Center
│   ├── Shipping Addresses
│   └── Coupons
└── Marketing Sub-application (Independently deployed)
    ├── Campaign Pages
    ├── Coupon Distribution
    └── Points Mall

Advantages of micro-frontends:

Team autonomy: Each sub-application develops and deploys independently
Technology-agnostic: Different teams can use different frameworks
Progressive upgrades: Legacy systems can be gradually refactored

4.3 Enterprise-Level Directory Structure

enterprise-project/
├── apps/                       # Micro-frontend sub-applications
│   ├── main/                   # Base application
│   ├── product/
│   ├── order/
│   └── user/
├── packages/                   # Shared packages (Monorepo)
│   ├── ui-components/          # Shared component library
│   ├── utils/                  # Utility functions
│   ├── constants/              # Constant definitions
│   └── types/                  # TypeScript types
├── shared/                     # Shared configuration
│   ├── eslint-config/
│   ├── ts-config/
│   └── vite-config/
├── docs/                       # Project documentation
├── scripts/                    # Build scripts
└── package.json

4.4 Performance Optimization Architecture

Large applications need to focus on performance optimization:

Performance Optimization Strategy/
├── Build-time Optimization
│   ├── Code Splitting
│   ├── Route Lazy Loading
│   ├── Tree Shaking
│   └── Asset Compression
├── Runtime Optimization
│   ├── Virtual Scrolling (long lists)
│   ├── Image Lazy Loading
│   ├── On-demand Component Rendering
│   └── Caching Strategy
└── Network Optimization
    ├── CDN Acceleration
    ├── HTTP Caching
    ├── Resource Preloading
    └── Service Worker

4.5 SSR/SSG Architecture

For scenarios requiring SEO or fast first-screen performance:

Approach	Suitable Scenarios	Representative Frameworks
SSR	Needs SEO, fast first-screen rendering	Next.js, Nuxt.js
SSG	Static content, infrequent updates	Astro, VitePress
Hybrid	Part static, part dynamic	Next.js (ISR)

5. Architecture Selection by User Scale

5.1 Individual/Small Team (Daily Active < 1,000)

Characteristics: Fast iteration, limited resources, rapidly changing requirements

Recommended Architecture:

Tech stack: Vue 3 + Vite or React + Vite
State management: Pinia or Zustand (lightweight)
UI library: Element Plus / Ant Design
Deployment: Vercel / Netlify / Cloud server

Directory Structure: Simple organization by type

5.2 Medium Enterprise (Daily Active 1k-100k)

Characteristics: Complex business, team collaboration, stability required

Recommended Architecture:

Tech stack: Vue 3 + TypeScript or React + TypeScript
State management: Pinia + composables or Redux Toolkit
UI library: In-house component library + business component library
Testing: Unit tests + E2E tests
Deployment: CI/CD pipeline + Docker

Directory Structure: Organize by feature, establish standards

5.3 Large Platform (Daily Active > 100k)

Characteristics: High concurrency, multi-team collaboration, long-term maintenance

Recommended Architecture:

Tech stack: React/Vue + TypeScript (strict mode)
Architecture: Micro-frontend + Monorepo
State management: Fine-grained state management + server state caching
Performance: SSR/SSG + CDN + Edge computing
Monitoring: Frontend monitoring + error tracking + performance analysis

Directory Structure: Monorepo + micro-frontend

6. Architecture Evolution Roadmap

6.1 Evolution Example: From Blog to Platform

Stage 1: Personal Blog (HTML/CSS/JS)
    ↓ Need: Backend management needed
Stage 2: Add Admin Panel (Vue/React + simple structure)
    ↓ Need: User system, comments feature
Stage 3: Feature Modularization (organize by feature)
    ↓ Need: Multi-team collaboration, independent deployment
Stage 4: Micro-frontend Architecture (Monorepo)

6.2 When Should You Upgrade Your Architecture?

Signal	Description	Suggestion
Build time > 5 minutes	Project too large	Code splitting, micro-frontend
Frequent merge conflicts	Collaboration difficulties	Organize by feature, module splitting
Fix one thing, break another	Severe coupling	Refactor, strengthen testing
First screen load > 3 seconds	Performance issues	Lazy loading, SSR, optimization
Slow onboarding for new members	Disorganized structure	Documentation, standards, refactoring

7. Summary

💡 Core Philosophy

There is no silver bullet for architecture — what fits is best.

Small projects: Don't over-engineer, HTML/CSS/JS is sufficient
Medium projects: Establish standards, componentization, modularization
Large projects: Consider micro-frontends, performance optimization, team collaboration

Remember these points:

Progressive evolution: Start simple, grow with needs
Unified conventions: Keep naming, structure, and code style consistent
Documentation first: Record architecture decisions for knowledge transfer
Regular refactoring: Pay off technical debt in a timely manner

Ultimate goal: Make code like an organized space — regardless of size, running efficiently.

Frontend Project Architecture Design ​

1. Architecture Evolution: From Simple to Complex ​

1.1 Three Complexity Levels Overview ​

2. Beginner Level: HTML/CSS/JS Projects ​

2.1 Suitable Scenarios ​

2.2 Recommended Directory Structure ​

2.3 Code Organization Principles ​

2.4 Best Practices ​

3. Intermediate Level: Vue/React Framework Projects ​

3.1 Suitable Scenarios ​

3.2 Vue Project Recommended Structure ​

3.3 React Project Recommended Structure ​

3.4 Key Concepts Explained ​

Component Design Principles ​

State Management Strategy ​

Directory Organization Approach Selection ​

4. Enterprise Level: Large Application Architecture ​

4.1 Suitable Scenarios ​

4.2 Micro-Frontend Architecture ​

4.3 Enterprise-Level Directory Structure ​

4.4 Performance Optimization Architecture ​

4.5 SSR/SSG Architecture ​

5. Architecture Selection by User Scale ​

5.1 Individual/Small Team (Daily Active < 1,000) ​

5.2 Medium Enterprise (Daily Active 1k-100k) ​

5.3 Large Platform (Daily Active > 100k) ​

6. Architecture Evolution Roadmap ​

6.1 Evolution Example: From Blog to Platform ​

6.2 When Should You Upgrade Your Architecture? ​

7. Summary ​

Reference Resources ​

Frontend Project Architecture Design

1. Architecture Evolution: From Simple to Complex

1.1 Three Complexity Levels Overview

2. Beginner Level: HTML/CSS/JS Projects

2.1 Suitable Scenarios

2.2 Recommended Directory Structure

2.3 Code Organization Principles

2.4 Best Practices

3. Intermediate Level: Vue/React Framework Projects

3.1 Suitable Scenarios

3.2 Vue Project Recommended Structure

3.3 React Project Recommended Structure

3.4 Key Concepts Explained

Component Design Principles

State Management Strategy

Directory Organization Approach Selection

4. Enterprise Level: Large Application Architecture

4.1 Suitable Scenarios

4.2 Micro-Frontend Architecture

4.3 Enterprise-Level Directory Structure

4.4 Performance Optimization Architecture

4.5 SSR/SSG Architecture

5. Architecture Selection by User Scale

5.1 Individual/Small Team (Daily Active < 1,000)

5.2 Medium Enterprise (Daily Active 1k-100k)

5.3 Large Platform (Daily Active > 100k)

6. Architecture Evolution Roadmap

6.1 Evolution Example: From Blog to Platform

6.2 When Should You Upgrade Your Architecture?

7. Summary

Reference Resources