Screaming Architecture

app/
├── components/
│   ├── Button.tsx
│   ├── Card.tsx
│   ├── UserForm.tsx
│   ├── ProductList.tsx
│   └── ShoppingCart.tsx
├── hooks/
│   ├── useAuth.ts
│   ├── useProducts.ts
│   └── useCart.ts
└── services/
    ├── authService.ts
    ├── productService.ts
    └── cartService.ts

app/
├── modules/
│   ├── authentication/      ← "I have authentication!"
│   │   ├── components/
│   │   ├── services/
│   │   └── hooks/
│   ├── products/            ← "I handle products!"
│   │   ├── components/
│   │   ├── services/
│   │   └── hooks/
│   └── shopping-cart/       ← "I have a shopping cart!"
│       ├── components/
│       ├── services/
│       └── hooks/

avangcli module user-profile --store zustand

modules/
└── user-profile/
    ├── components/          # Reusable UI components of the module
    ├── containers/          # Container components (logic + UI)
    │   └── user-profile-container.tsx
    ├── services/            # Business logic
    │   └── user-profile.service.ts
    ├── types/               # TypeScript definitions
    │   └── user-profile.types.ts
    ├── hooks/               # Custom React hooks
    ├── store/               # Module state
    │   └── user-profile.store.ts
    ├── adapters/            # Adapters for external APIs
    ├── helpers/             # Helper functions
    ├── lib/                 # Module-specific utilities
    └── index.ts             # Barrel export

components/
  UserCard.tsx
  UserList.tsx
  ProductCard.tsx
  ProductList.tsx
services/
  userService.ts
  productService.ts

modules/
  user/
    components/
      UserCard.tsx
      UserList.tsx
    services/
      user.service.ts
  product/
    components/
      ProductCard.tsx
      ProductList.tsx
    services/
      product.service.ts

modules/
  user-profile/
    components/
      Avatar.tsx              ← Only used in user-profile
    services/
      user-profile.service.ts ← Only for this module

shared/
  components/
    Button.tsx               ← Used in multiple modules

modules/
  user-profile/
    containers/              ← Highest level: Orchestrates everything
      user-profile-container.tsx
    components/              ← Middle level: UI components
      ProfileHeader.tsx
    services/                ← Low level: Business logic
      user-profile.service.ts
    types/                   ← Foundation: Contracts
      user-profile.types.ts

# You know exactly where to go:
modules/user-profile/

# Add product reviews
avangcli module product-reviews --store zustand

# Add wishlist
avangcli module wishlist --store zustand

"What does this app do?"
→ Looks at `modules/`
→ "Ah, it handles users, products, shopping-cart and orders"

"What does this app do?"
→ Looks at `components/`, `hooks/`, `services/`
→ "Uh... I don't know, let me review each file"

// user-profile.test.ts
import { userProfileService } from "@/modules/user-profile"

describe("UserProfile Module", () => {
  // Test the entire module in isolation
})

# Simply delete the entire module
rm -rf modules/deprecated-feature

// Container
export const UserProfileContainer = () => {
  const [user, setUser] = useState()
  const loadUser = async () => { /* logic */ }

  return <UserProfileView user={user} />
}

// Component (presentational)
export const UserProfileView = ({ user }) => {
  return <div>{user.name}</div>
}

export class UserProfileService {
  private static instance: UserProfileService

  async fetchProfile() {
    /* ... */
  }
  async updateProfile() {
    /* ... */
  }
}

export interface UserProfile {
  id: string
  name: string
  email: string
}

// Zustand store
export const useUserProfileStore = create((set) => ({
  profile: null,
  setProfile: (profile) => set({ profile })
}))

// If you change from REST to GraphQL, only modify the adapter
export class UserApiAdapter {
  async fetchUser(id: string) {
    // REST implementation
    return fetch(`/api/users/${id}`)
  }
}

export function useUserProfile(userId: string) {
  const [profile, setProfile] = useState()

  useEffect(() => {
    // Loading logic
  }, [userId])

  return { profile }
}

shared/
  components/
    Button.tsx        ← Used everywhere
    Modal.tsx
  hooks/
    useAuth.ts        ← Global authentication
  types/
    common.types.ts   ← Shared types

config/
  api.config.ts
  theme.config.ts

utils/
  formatDate.ts
  validators.ts