About Module Architecture I've been freelancing for 7 years and have done more than 20 projects for about 10 clients. In my previous article, I talked about modular architecture and how it helped me work faster across all my projects. In short, modular architecture is when you keep all code for one feature in one folder. Here is a simple example of how it looks: src/
  modules/
    user-management/
      UserProfile/
        UserProfile.tsx
        UserProfile.module.css
        index.ts
      slice.ts
      types.ts
      api.ts
      index.ts
  components/
    Button/
      Button.tsx
      Button.module.css
      index.ts
  pages/
    Users/
      Users.tsx
      Users.module.css
      index.ts src/
  modules/
    user-management/
      UserProfile/
        UserProfile.tsx
        UserProfile.module.css
        index.ts
      slice.ts
      types.ts
      api.ts
      index.ts
  components/
    Button/
      Button.tsx
      Button.module.css
      index.ts
  pages/
    Users/
      Users.tsx
      Users.module.css
      index.ts All user-related code, like components, types, API calls, and state, lives inside the user-management folder. In this article, I want to show how this approach also helps you spend fewer tokens when you work with AI coding tools like Claude Code. I will use a React.js application as an example. How modular architecture helps to save tokens when working with AI coding tools. For example, imagine you need to add a new field to the user profile form. In a traditional architecture, Claude Code needs to open src/types/user.ts to update the type, then src/api/userApi.ts to update the request, then src/components/UserProfile.tsx to update the UI, and maybe src/store/userSlice.ts to update the state. These files are spread across different folders and mixed with code from other features. src/types/user.ts src/api/userApi.ts src/components/UserProfile.tsx src/store/userSlice.ts In modular architecture, all of this is in one place: modules/user-management/. Claude Code opens the module, does the work, and never touches anything else. modules/user-management/ Documentation for non-technical people. I recommend adding a README file with a short description of each module. This can help non-technical people understand what each module does and make changes using an AI tool without knowing all the technical details. Each module description should include the browser path and a screenshot so a non-technical person can see which part of the app the module is responsible for. You can also use Claude Code PostToolUse hooks to keep this documentation up to date. After each change, Claude Code can scan the modules and update the README automatically so your documentation always stays in sync with the code. As a freelancer in the era of AI, you need to give your client the ability to maintain the project without you using modern tools. Claude Code hooks are very helpful with modular architecture. You can use PreToolUse and PostToolUse hooks to add special attention to critical modules like auth and roles. Because your code is organized in separate module folders, it is very easy to target a specific module with a hook. For example, a PreToolUse hook for the auth module that asks for confirmation before any change: {
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if echo '$CLAUDE_TOOL_INPUT' | grep -q 'modules/auth'; then echo 'WARNING: You are modifying the auth module. This affects login, tokens and permissions.' && read -p 'Are you sure? (y/n) ' confirm && [ \"$confirm\" = 'y' ]; fi"
          }
        ]
      }
    ]
  }
} {
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if echo '$CLAUDE_TOOL_INPUT' | grep -q 'modules/auth'; then echo 'WARNING: You are modifying the auth module. This affects login, tokens and permissions.' && read -p 'Are you sure? (y/n) ' confirm && [ \"$confirm\" = 'y' ]; fi"
          }
        ]
      }
    ]
  }
} Let's imagine you do not have the budget to cover the whole application with unit tests, and your client asks you to cover only the important parts, like roles. In this case, a PostToolUse hook is a great fit. Every time Claude Code makes a change inside the roles module, the hook runs the tests automatically, so you always know if something was broken: {
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "if echo '$CLAUDE_TOOL_INPUT' | grep -q 'modules/roles'; then npm run test -- --testPathPattern=roles; fi"
          }
        ]
      }
    ]
  }
} {
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "if echo '$CLAUDE_TOOL_INPUT' | grep -q 'modules/roles'; then npm run test -- --testPathPattern=roles; fi"
          }
        ]
      }
    ]
  }
} Conclusion Modular architecture is not just a way to organize your code. It is a way to work smarter with AI tools. When your code is split into focused modules, each AI task stays inside one folder, uses fewer tokens, and makes changes that are easy to review and control. With a good README, your clients can use AI tools to make simple changes without understanding the whole codebase. And with Claude Code hooks, you can protect the parts of your app that matter most. The modular approach was useful before AI tools existed. Now it is even more useful.

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

This story contains AI-generated text. The author has used AI either for research, to generate outlines, or write the text itself. 

Why Modular Architecture Makes AI Coding Tools Work Better

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

I Spent Years Freelancing in Web Dev—Here’s the Modular Trick That Saved My Sanity

Senior Engineers Know the Hardest Part Isn’t Coding

The Reliability Cost of Default Timeouts

The Most Dangerous Sentence in Software Engineering: “We Can Build This Better”

How Artificial Neural Networks Can Code Smarter Than GUI Programmer

How GPT Pilot Codes 95% of Your App

I Spent Years Freelancing in Web Dev—Here’s the Modular Trick That Saved My Sanity

Senior Engineers Know the Hardest Part Isn’t Coding

The Reliability Cost of Default Timeouts

The Most Dangerous Sentence in Software Engineering: “We Can Build This Better”

How Artificial Neural Networks Can Code Smarter Than GUI Programmer

How GPT Pilot Codes 95% of Your App

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps