Forem: Truong Vu

Claude Rock

Truong Vu — Thu, 23 Oct 2025 11:04:27 +0000

I've built Claude Rock, a marketplace for Claude Skills.
Its first skill is a Architecture Design that can generate complete, professional-grade architecture documentation — including diagrams, specs, and design rationales — in just minutes.

💡 What it does:

Runs a short 5–7 question interview to gather your system details
Generates a full 11-section architecture doc
Creates C4 + data flow diagrams, OpenAPI specs

🗣️ How to chat with it: Once installed, just talk to Claude naturally — for example:

“Create architecture documentation for my Node.js e-commerce app.” “Design a serverless architecture on AWS using Python.” “Update the architecture to include Redis caching.”

Claude will ask you a few questions, then generate a complete, professional architecture document — including diagrams and best practices.

⚡ Why it’s useful: What normally takes hours now takes a few minutes — perfect for dev teams, architects, or anyone standardizing documentation.

💡 Quick install:

/plugin marketplace add vukhanhtruong/claude-rock  
/plugin install architecture-design@claude-rock

📘 Get the skill + guide: GitHub

💾 Sample output: Check out a Trello clone architecture doc generated by the skill.

Build a Note app with Clean Architecture and C4 Model

Truong Vu — Tue, 04 Feb 2025 04:18:20 +0000

If you did not read the previous post about how to visualize the software architecture with C4 model, I would recommend to read it to have a big picture of what/how this app was built.

As the Architecture Decisions Records were approved, the tech stack will be:

Clean Architecture
TypeScript
Prisma
Cloudflare Workers with a D1 Database.
Hono Framework

Demo

To help you better understand the concepts and see Clean Architecture in action, I’ve prepared a demo application for you. This demo uses the Note Taker App as a real-world example.

Source code: You can explore the full source code on GitHub. Feel free to clone the repo, experiment with the code.

Live Demo:

Clean Architecture

This diagram makes more sense to me compared to the original circular one. The color code is still consistent with the original. I hope it works for you too.

Clean Architecture is a set of rules that help us structure our application in such way that it will be easier to maintain and test. It’s kind of like a common language that helps developers understand each other.

I would highly recommend to read Clean Architecture book, it can elevate your understanding of software design to a new level. Here’s a quick summary based on my experience. Let me know your thought — feedback is always welcome:

At high-level, Clean Architecture provides a structured and abstract way to interact with the core business logic, similar like how an ORM abstracts and organizes interactions with a database.
It prioritizes independence and loose coupling, allowing different parts of your system to function independently.
Clean Architecture helps to organize the system with the core business logic at the center.
Unlike traditional layered architectures (e.g., 3-Tier or N-Tier), Clean Architecture focuses on controlling dependencies to keep components decoupled and maintainable.
The business logic is not couple to any framework, meaning you could later create a CLI or any type application without modifying the business logic.
All communication with business logic is facilitated through interfaces (abstractions).
Testable - Since the business logic doesn’t rely on external dependencies, it’s easy to test. The Use Case Interactor (or just "Use Case") is the primary location where you should focus on testing business logic and application rules. It is the core component that orchestrates and enforces the application's business rules, making it the ideal layer for concentrated testing.

Note Taker App

Project Structure (important ones only)

How you organize your project is up to your team, as long as everyone stays on the same page and communicates effectively day to day. Here’s an example structure for this app:

core: Contains reusable classes that can be used across multiple domains.

controller/http: Whatever consuming the business logic will be here. In this demo, it’s the Hono framework.

provider.ts: Manages dependency injection, setting up the DI container and modules.

prisma: Handles schema definitions and migrations using Prisma ORM.

domain: The most critical folder—it contains the core business rules

entity: Holds the models

exceptions: Defines custom error handling.

interactor: Where business use cases are executed. Unit tests go here.

infra: Contains database implementations (e.g., D1 in this case) and third-party services.

port:

persistence: Acts as the Output Port in Clean Architecture. This is the repository interface, enabling the Use Case Interactor to query, save, or update data without knowing the details of the database implementation.
usecase: Acts as the Input Port in Clean Architecture. It abstracts how external layers (like controllers) interact with business logic.

Summary

At first glance, Clean Architecture might seem like over-engineering, but it's really about creating discipline and predictability in your code base. By defining clear rules about where everything belongs, it simplifies feature development and makes your code easier to work with.

Without structure, your code base will eventually turn into a mess, slowing down progress and forcing you to come up with rules the hard way. Clean Architecture saves you from that pain by providing a proven approach that’s been tested over time. Learn it once, and you can use it in any project, making your code maintainable and scalable from the start.

You should NOT apply Clean Architecture to every project. For projects with strict time constraints or smaller scopes, the added complexity may outweigh the benefits. Additionally, if team members are unfamiliar with Clean Architecture, the learning curve can slow development and reduce efficiency. It's best suited for larger, long-term projects where maintainability and scalability are critical.

What’s Next?

Start by applying Clean Architecture principles to a real-world project, just start with a small one.
Deepen your understanding of related concepts like SOLID principles, Domain-Driven Design (DDD).
Explore advanced topics like Dependency Injection (DI), design patterns, and event-driven architecture to enhance your architectural skills.

Caching Problems You Should Know

Truong Vu — Mon, 18 Nov 2024 03:53:30 +0000

Caching is one of the most powerful tools to improve application performance and scalability, reduces back-end load, decreases latency, better user experience. However, it also comes up with challenges.

As a developer, I’ve relied on caching to optimize application performance, one of my frequently used approach is Cache-Aside strategy - it’s simple, works well for most scenarios. Along the way, I’ve encountered issues like Thundering herd problem, Cache Stampede, and several others, which make me to rethink how I handling caching.

In this post, I’ll share my personal experiences with these problems, what went wrong, and how to resolved them.

How Cache-Aside Strategy Works

Basically, the application will determine whether the item is currently held in the cache. Then if item is not available, it will read the item from the database (MySQL). After that, it will store a copy of the item in the cache.

What went wrong

One of my projects involved a high-traffic API for delivering editorial content. We used cache-aside strategy to store the content within a 5-minute expiration. It worked fine until it didn’t.

The popular contents expired at the same time
The back-end is flooded with requests, struggling to handle the load.
A huge number of requests reading the same key which had expired. Then, all of them directly read data from database, it just simply couldn’t keep up.

Solutions

After digging into the issue, it became clear that the back-end had scaled up to its maximum allowed capacity, while the database was overwhelmed by the surge in requests. This was leading to degraded performance or even system crashes.

Thundering Herd Problem

Workaround: One of approaches is to use randomized expiration times for cache keys. This prevents them from expiring simultaneously. There are other solutions to solve this issue as well, and if you find it interesting, a quick googling will reveal many of helpful resources and solutions.

Pseudo-code:

Cache Stampede

Workaround:: Since I was using Redis as the caching layer, I tackled this problem by implementing a Redis distributed lock. The lock ensures that only one process can update the cache at a time, while other processes must wait for the update to complete. This approach effectively prevents multiple processes from overwhelming the back-end simultaneously.

Pseudo-code:

Lesson Learned

If you’re using caching, challenges like Thundering Herd, Cache Stampede, and others are inevitable. My experience has shown me that nothing is perfect, it’s better to have proper planning.

Have you faced similar caching challenges? How did you overcome them?

Level up the quality of your javascript code base with Babel and ESLint.

Truong Vu — Sat, 20 Apr 2019 10:36:27 +0000

In this post, we will setup ESlint, Prettier to ensure that our code has the same format throughout this project. Babel is a transpiler that can turn our ES6 code into ES5. I’m going to assume you know how to use both node and npm and have them both installed on your machine.

Project Setup

Create a directory and run the following command.

npm init

For this tutorial, I will be adding an index.js file to the src folder, and this will be our entry point. Our file directory should look like this.

your-project/
|--src/
  |--index.js
|--package.json

Install Packages

Nodemon

Nodemon is a tool that helps develop Js/Nodejs based applications by automatically restarting the node application when file changes detected.

npm install nodemon --save-dev

Babel

Babel is a tool that is used to convert ECMAScript 2015+ code into a backward compatible version of JavaScript so that older browsers and environment will be able to understand your code.

Run the following command to install babel:

npm install @babel/core \ 
            @babel/cli \ 
            @babel/preset-env \
            @babel/node \
            @babel/runtime --save-dev

Next, we need to tell babel how to transpile our files by creating a .babelrc file in the root directory and adding the following code to it.

{
  "presets": [
    "@babel/preset-env"
  ]
}

[Optional] If you want to set up a custom alias for directories, specific files, or even other npm modules. Let's take a look to this handy plugin

ESLint + Airbnb JS style guide + Prettier

These tools will be identifying, reporting and formatting on patterns found in ECMAScript/JavaScript code, with the goal of making the code more consistent and avoiding bugs.

Run the following command to install:

npm install eslint \
            eslint-config-airbnb-base \
            eslint-config-prettier \
            eslint-plugin-import \
            eslint-plugin-prettier \
            prettier --save-dev

Prettier Configuration

Create the file named .prettierrc in the root directory and adding the following code to it.

{
  "trailingComma": "es5",
  "tabWidth": 4,
  "semi": false,
  "singleQuote": true
}

If you'd like a JSON schema to validate your configuration, one is available here: http://json.schemastore.org/prettierrc.

Eslint Configuration

Create the file named .eslintrc.json in the root directory and add the following code to it.

{
  "extends": ["airbnb-base", "plugin:prettier/recommended"],
  "plugins": ["prettier"],
  "rules": {
    "prettier/prettier": "error"
  }  
}

Scripts

Open up package.json then add the following code to the scripts section

{
  ...
  "scripts": {
    "build": "babel ./src --out-dir ./build",
    "start": "nodemon --exec babel-node src/index.js",
    "lint": "eslint ."
  },
  ...
}

Integrated with VSCode

Install Prettier and ESLint extensions

Configure VS Code

{
  ..
  "editor.formatOnSave": true,
  ..
}

Check my gist to find the final files.

Happy coding!

Things to remember when reinstall Ubuntu.

Truong Vu — Sat, 19 Jan 2019 12:06:07 +0000

This is just about my checklist when I reinstall the software on my machine. Hope you have find this useful.

Backup the essential things.

The most important thing is the folder named ~/.ssh where contains all my credentials to access to different servers. As you well know if you lost it, you have to re-generate keys and add them to Github, Gitlab, Bitbucket, etc.
Make sure all source code was backed up or pushed to the remote repository.
My favorite IDE is Visual Studio Code, and there are a lot of extensions was installed. All I need to do is backup the folder named .vscode in my home directory ~/.vscode. If you were using another IDE, you should find out where the configuration store then saves it.
I work with the terminal every day, so I have to backup the file named .zshrc and the folder named .oh-my-zsh, to avoid re-configuration the terminal and install a dozen of plugins.

After finishing installing Ubuntu

Move all the backed up folder to the same path like before. So, now my Linux environment similar to the old one. Definitely, it saves my time.
Install the favorite apps. Here are my favorite applications, just focused on development.

System

Ubuntu 18.10 (current)

IDE

Visual studio code

Internet

Chrome
Rambox All-in-one chat apps.

Terminal

zsh
p10k
neovim
tmux and tmuxinator
oh-my-zsh A delightful community-driven (with 1,200+ contributors) framework for managing your zsh configuration. Below is my favorite plugins:

plugins=(
  zsh-completions
  zsh-autosuggestions
  zsh-syntax-highlighting
  history-substring-search
  git
  docker
  docker-compose
  dotenv
  nvm
  httpie
  rsync
  yarn
  tmux
  node
  helm
  composer
  minikube
  kubectl
)

vimrc — This configuration is the ultimate vimrc.
vim-plug — Plugins management.
vim languages pack
vim syntax checker

call plug#begin('~/.vim/plugged')

" Make sure you use single quotes

" On-demand loading
Plug 'scrooloose/nerdtree', { 'on':  'NERDTreeToggle' }

" Language pack for VIM
Plug 'sheerun/vim-polyglot'

" VIM check syntax
Plug 'w0rp/ale' 

" Initialize plugin system
call plug#end()

" Shortcut key to open file explorer
nmap <F6> :NERDTreeToggle<CR>

" ALE linting tool
let g:ale_linters = {
\   'javascript': ['eslint'],
\}

let g:ale_sign_error = '❌'
let g:ale_sign_warning = '⚠️'
highlight ALEErrorSign ctermbg=NONE ctermfg=red
highlight ALEWarningSign ctermbg=NONE ctermfg=yellow

let g:ale_fixers['javascript'] = ['eslint']

" Fix files automatically on save
let g:ale_fix_on_save = 1

DevOps Tools

docker
docker-compose
minikube
skaffold A command line tool that facilitates continuous development for Kubernetes applications.
kompose Converts Docker Compose to Kubernetes.
kubectl Command line interface for running commands against Kubernetes clusters.
kubectx Fast way to switch between clusters and namespaces in kubectl.
kubeval Validate your Kubernetes configuration files, supports multiple Kubernetes versions.
dive A tool for exploring each layer in a docker image

Utilities Dev Tools

fd - A simple, fast and user-friendly alternative to 'find'.
cheat.sh The only cheat sheet you need.
httpie — Modern command line HTTP client — user-friendly curl alternative with intuitive UI, JSON support, syntax highlighting, wget-like downloads, extensions, etc.
postman Postman Makes API Development Simple.
ngrok or localtunnel Exposes your localhost to the world for easy testing and sharing.
pet — Simple command-line snippet manager.
tmux — Terminal multiplexer.
tmux config — The best tmux configuration.
mycli — A Terminal Client for MySQL with AutoCompletion and Syntax Highlighting.
json-server — Get a full fake REST API with zero coding in less than 30 seconds.
vegeta HTTP load testing tool and library.
mkcert A simple zero-config tool to make locally trusted development certificates with any names you'd like.
doctoc Generates table of contents for markdown files.

Troubleshooting

If you got the following issue with ssh:

sign_and_send_pubkey signing failed agent refused operation

Run the following command to fix:

eval "$(ssh-agent -s)" && ssh-add ~/.ssh/id_rsa
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_rsa
chmod 644 ~/.ssh/id_rsa.pub

That's it. If you have anything to share, feel free to leave your comment.

Structuring Node.js Project

Truong Vu — Thu, 22 Nov 2018 05:07:14 +0000

If you are looking for the NodeJS project structure based on the best practices to build the RESTful API. It might be helpful for you guys.

Some of the good practices followed in this repository:

Code Style Practices via Node Best Practices
ES6 Support.
Morgan Logger.
Error Handling.
Open API Specification implemented through apidocjs.
JWT Authentication.
Joi & Express Validation.
Environment variables via .env file.
Linting with Prettier.
Security (Helmet, CORS, Express Brute).
Husky as git hook for linting & running unit test before commit.
Unit & E2E Testing with Jest.
Backpack build system

Prerequisite

NodeJS
Node Package Management (yarn or npm)
Docker

Installation

Clone the project git clone git@github.com:vukhanhtruong/nodejs-api-boilerplate.git.
Install dependencies yarn install or npm i
Copy .env.example to .env file.

Running Docker

docker-compose up -d.

Raven Log

Create account at Sentry, then put your url to .env file at variable SENTRY_DSN.

Api Doc

Api Doc is hosted on surge. For change the url and have your own docs just modify your link in the .env file. Running the following command to publish your documentation.

# Generate document
yarn doc
# Deploy document to surge.sh
yarn doc:deploy

# or
npm run doc
npm run doc:deploy

Pre-Commit Hook

Using husky for linting your code before commit & running unit test before push.

Scripts

DEV

yarn dev

# or

npm run dev

DEBUG

Debug with VSCode. See VSCode Auto-Attach

yarn debug

# or

npm run debug

TEST

yarn test

# or

npm run test

NOTE: If you have the issue with ENOSPC, run the below command to avoid:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

Test Watch

yarn test:watch

COVERAGE

# run jest coverage
yarn test:cover

# show html report
yarn test:cover:open

# or

npm run test:cover

npm run test:cover:open

JSDOC

# generate documentation
yarn doc

# Publish documentation to surge.sh
yarn doc:deploy

#or

npm run doc

npm run doc:deploy

Find out more here

Happy Coding!