Chapter 4: Project Structure in C++

How to organize your Kungfu.js project. In this chapter, you will learn project structure in depth with C++ code examples, explanations, and best practices.

Overview

This chapter covers project structure for Kungfu.js developers using C++. We will start with the basics, move through practical examples, and end with advanced techniques and common pitfalls.

Why This Matters

Understanding project structure is essential because it is a core part of building web applications. Every real-world app needs to handle how to organize your kungfu.js project. Skipping this chapter would leave a gap in your knowledge that would cause problems later.

Code Example

This chapter covers project structure in C++. Below is a practical code example you can copy, run, and modify to solidify your understanding.

my-app/
├── src/
│   ├── main.rs          # or app.jsk / app.py — your entry point
│   ├── handlers/
│   │   ├── users.rs     # route handlers grouped by resource
│   │   └── todos.rs
│   ├── middleware/
│   │   └── auth.rs      # custom middleware
│   └── models/
│       └── user.rs      # #[derive(Model)] structs
├── pages/
│   ├── index.kng        # SSR frontend pages
│   └── dashboard.kng
├── static/              # CSS, images, fonts
├── migrations/          # SQL migration files
├── Cargo.toml           # Rust dependencies (or package.json / pyproject.toml)
└── kungfu.toml          # Kungfu.js config (port, features, middleware)

# The kungfu.toml file:
[server]
port = 3000
host = "0.0.0.0"

[features]
io_uring = true      # Linux 5.1+ zero-copy I/O
simd = true          # x86_64 AVX2 JSON acceleration

[middleware]
security_headers = true
cors = { origins = ["https://myapp.com"] }
rate_limiter = { burst = 200, rps = 100 }
logger = true

Why This Matters

Every feature in Kungfu.js is designed to be predictable: the same input always produces the same output, the same route always hits the same handler, and the same middleware always runs in the same order. This predictability is what makes production apps maintainable. When something breaks at 3 AM, you need to reason about the request path quickly — and the onion-model middleware plus the trie router give you that mental model for free.

Common Mistakes

  • Not reading the documentation: Always check the API reference when something does not work as expected.
  • Skipping security: Never disable the default middleware unless you have a very good reason. Security is not optional.
  • Not testing: Write tests for your handlers. Kungfu.js makes this easy with the built-in test utilities.

Summary

In this chapter, you learned about project structure in C++. You saw code examples, understood how things work under the hood, and learned about common mistakes to avoid.

What is Next?

In chapter 5, we will cover Routing Basics: Static routes and the trie router explained.

Previous: Hello World ExplainedNext: Routing Basics