refactor(new): improve backend and web templates

Author: GaspardKirira

include/vix/cli/commands/new/templates/backend/BackendTemplateUtils.hpp

@@ -0,0 +1,34 @@
+/**
+ * @file BackendTemplateUtils.hpp
+ * @author Gaspard Kirira
+ *
+ * Copyright 2025, Gaspard Kirira.  All rights reserved.
+ * https://github.com/vixcpp/vix
+ * Use of this source code is governed by a MIT license
+ * that can be found in the License file.
+ */
+
+#ifndef VIX_CLI_COMMANDS_NEW_TEMPLATES_BACKEND_TEMPLATE_UTILS_HPP
+#define VIX_CLI_COMMANDS_NEW_TEMPLATES_BACKEND_TEMPLATE_UTILS_HPP
+
+#include <string>
+
+namespace vix::commands::new_cmd::templates
+{
+  /**
+   * @brief Build a stable include guard for a generated backend header.
+   *
+   * The generated guard includes the project name and a file-specific suffix
+   * to avoid collisions between generated headers and installed Vix headers.
+   *
+   * @param projectName Name of the generated backend project.
+   * @param suffix File-specific suffix, for example APP_BOOTSTRAP or HOME_CONTROLLER.
+   * @return Include guard name.
+   */
+  std::string make_backend_header_guard(
+      const std::string &projectName,
+      const std::string &suffix);
+
+} // namespace vix::commands::new_cmd::templates
+
+#endif // VIX_CLI_COMMANDS_NEW_TEMPLATES_BACKEND_TEMPLATE_UTILS_HPP

include/vix/cli/commands/new/templates/web/WebTemplateUtils.hpp

@@ -0,0 +1,31 @@
+/**
+ * @file WebTemplateUtils.hpp
+ * @author Gaspard Kirira
+ *
+ * Copyright 2025, Gaspard Kirira.  All rights reserved.
+ * https://github.com/vixcpp/vix
+ * Use of this source code is governed by a MIT license
+ * that can be found in the License file.
+ */
+
+#ifndef VIX_CLI_COMMANDS_NEW_TEMPLATES_WEB_TEMPLATE_UTILS_HPP
+#define VIX_CLI_COMMANDS_NEW_TEMPLATES_WEB_TEMPLATE_UTILS_HPP
+
+#include <string>
+
+namespace vix::commands::new_cmd::templates
+{
+  /**
+   * @brief Build a stable include guard for a generated web header.
+   *
+   * @param projectName Name of the generated web project.
+   * @param suffix File-specific suffix, for example APP_BOOTSTRAP.
+   * @return Include guard name.
+   */
+  std::string make_web_header_guard(
+      const std::string &projectName,
+      const std::string &suffix);
+
+} // namespace vix::commands::new_cmd::templates
+
+#endif // VIX_CLI_COMMANDS_NEW_TEMPLATES_WEB_TEMPLATE_UTILS_HPP

src/commands/new/templates/backend/BackendBootstrapTemplates.cpp

@@ -9,7 +9,9 @@
  */
 
 #include <vix/cli/commands/new/templates/backend/BackendBootstrapTemplates.hpp>
-
+#include <vix/cli/commands/new/templates/backend/BackendTemplateUtils.hpp>
+#include <algorithm>
+#include <cctype>
 #include <string>
 
 namespace vix::commands::new_cmd::templates
@@ -18,9 +20,24 @@ namespace vix::commands::new_cmd::templates
   std::string make_backend_main_cpp(const std::string &projectName)
   {
     std::string s;
-    s.reserve(400);
+    s.reserve(900);
+
+    s += "/**\n";
+    s += " * @file main.cpp\n";
+    s += " * @brief Entry point for the " + projectName + " backend application.\n";
+    s += " */\n\n";
 
     s += "#include <" + projectName + "/app/AppBootstrap.hpp>\n\n";
+
+    s += "/**\n";
+    s += " * @brief Start the backend application.\n";
+    s += " *\n";
+    s += " * The main function stays intentionally small. Application setup,\n";
+    s += " * middleware registration, route registration, and server startup are\n";
+    s += " * delegated to " + projectName + "::app::AppBootstrap.\n";
+    s += " *\n";
+    s += " * @return Process exit code.\n";
+    s += " */\n";
     s += "int main()\n";
     s += "{\n";
     s += "  " + projectName + "::app::AppBootstrap bootstrap;\n";
@@ -32,49 +49,93 @@ namespace vix::commands::new_cmd::templates
 
   std::string make_backend_app_bootstrap_hpp(const std::string &projectName)
   {
+    const std::string guard = make_backend_header_guard(projectName, "APP_BOOTSTRAP");
+
     std::string s;
-    s.reserve(900);
+    s.reserve(1600);
+
+    s += "/**\n";
+    s += " * @file AppBootstrap.hpp\n";
+    s += " * @brief Application bootstrap for the " + projectName + " backend.\n";
+    s += " */\n\n";
+
+    s += "#ifndef " + guard + "\n";
+    s += "#define " + guard + "\n\n";
 
-    s += "#pragma once\n\n";
     s += "namespace " + projectName + "::app\n";
     s += "{\n";
+    s += "  /**\n";
+    s += "   * @brief Owns the startup sequence of the backend application.\n";
+    s += "   *\n";
+    s += "   * AppBootstrap keeps main.cpp minimal and centralizes the application\n";
+    s += "   * initialization flow: configuration loading, Vix app creation,\n";
+    s += "   * template/static directory setup, middleware registration, route\n";
+    s += "   * registration, and server startup.\n";
+    s += "   */\n";
     s += "  class AppBootstrap\n";
     s += "  {\n";
     s += "  public:\n";
-    s += "    AppBootstrap() = default;\n";
+    s += "    /**\n";
+    s += "     * @brief Create a default application bootstrap instance.\n";
+    s += "     */\n";
+    s += "    AppBootstrap() = default;\n\n";
+
+    s += "    /**\n";
+    s += "     * @brief Destroy the application bootstrap instance.\n";
+    s += "     */\n";
     s += "    ~AppBootstrap() = default;\n\n";
+
     s += "    AppBootstrap(const AppBootstrap &) = delete;\n";
     s += "    AppBootstrap &operator=(const AppBootstrap &) = delete;\n";
     s += "    AppBootstrap(AppBootstrap &&) = delete;\n";
     s += "    AppBootstrap &operator=(AppBootstrap &&) = delete;\n\n";
+
+    s += "    /**\n";
+    s += "     * @brief Run the backend application.\n";
+    s += "     *\n";
+    s += "     * @return Process exit code. Returns 0 when the application exits normally.\n";
+    s += "     */\n";
     s += "    int run();\n";
     s += "  };\n";
-    s += "} // namespace " + projectName + "::app\n";
+    s += "} // namespace " + projectName + "::app\n\n";
+
+    s += "#endif // " + guard + "\n";
 
     return s;
   }
 
   std::string make_backend_app_bootstrap_cpp(const std::string &projectName)
   {
     std::string s;
-    s.reserve(2400);
+    s.reserve(3200);
+
+    s += "/**\n";
+    s += " * @file AppBootstrap.cpp\n";
+    s += " * @brief Startup implementation for the " + projectName + " backend.\n";
+    s += " */\n\n";
 
     s += "#include <" + projectName + "/app/AppBootstrap.hpp>\n";
     s += "#include <" + projectName + "/presentation/middleware/MiddlewareRegistry.hpp>\n";
     s += "#include <" + projectName + "/presentation/routes/RouteRegistry.hpp>\n\n";
+
     s += "#include <vix.hpp>\n";
     s += "#include <vix/log.hpp>\n\n";
+
     s += "namespace " + projectName + "::app\n";
     s += "{\n";
     s += "  int AppBootstrap::run()\n";
     s += "  {\n";
     s += "    vix::config::Config cfg{\".env\"};\n";
     s += "    vix::App app;\n\n";
+
     s += "    app.templates(\"views\");\n";
     s += "    app.static_dir(\"public\", \"/\");\n\n";
+
     s += "    presentation::middleware::MiddlewareRegistry::register_all(app);\n";
     s += "    presentation::routes::RouteRegistry::register_all(app);\n\n";
+
     s += "    vix::log::info(\"Starting " + projectName + " on port {}\", cfg.getServerPort());\n\n";
+
     s += "    app.run(cfg);\n";
     s += "    return 0;\n";
     s += "  }\n";

src/commands/new/templates/backend/BackendControllerTemplates.cpp

@@ -9,41 +9,71 @@
  */
 
 #include <vix/cli/commands/new/templates/backend/BackendControllerTemplates.hpp>
+#include <vix/cli/commands/new/templates/backend/BackendTemplateUtils.hpp>
 
+#include <cctype>
 #include <string>
 
 namespace vix::commands::new_cmd::templates
 {
-
   std::string make_backend_home_controller_hpp(const std::string &projectName)
   {
+    const std::string guard = make_backend_header_guard(projectName, "HOME_CONTROLLER");
+
     std::string s;
-    s.reserve(800);
+    s.reserve(1700);
+
+    s += "/**\n";
+    s += " * @file HomeController.hpp\n";
+    s += " * @brief Home API routes for the " + projectName + " backend.\n";
+    s += " */\n\n";
+
+    s += "#ifndef " + guard + "\n";
+    s += "#define " + guard + "\n\n";
 
-    s += "#pragma once\n\n";
     s += "namespace vix\n";
     s += "{\n";
     s += "  class App;\n";
     s += "}\n\n";
+
     s += "namespace " + projectName + "::presentation::controllers\n";
     s += "{\n";
+    s += "  /**\n";
+    s += "   * @brief Registers public home routes for the backend API.\n";
+    s += "   *\n";
+    s += "   * HomeController owns lightweight routes that are useful for verifying\n";
+    s += "   * that the generated backend is reachable and correctly wired.\n";
+    s += "   */\n";
     s += "  class HomeController\n";
     s += "  {\n";
     s += "  public:\n";
+    s += "    /**\n";
+    s += "     * @brief Register the home routes on the given Vix application.\n";
+    s += "     *\n";
+    s += "     * @param app Target application receiving the routes.\n";
+    s += "     */\n";
     s += "    static void register_routes(vix::App &app);\n";
     s += "  };\n";
-    s += "} // namespace " + projectName + "::presentation::controllers\n";
+    s += "} // namespace " + projectName + "::presentation::controllers\n\n";
+
+    s += "#endif // " + guard + "\n";
 
     return s;
   }
 
   std::string make_backend_home_controller_cpp(const std::string &projectName)
   {
     std::string s;
-    s.reserve(1500);
+    s.reserve(2200);
+
+    s += "/**\n";
+    s += " * @file HomeController.cpp\n";
+    s += " * @brief Home route implementation for the " + projectName + " backend.\n";
+    s += " */\n\n";
 
     s += "#include <" + projectName + "/presentation/controllers/HomeController.hpp>\n\n";
     s += "#include <vix.hpp>\n\n";
+
     s += "namespace " + projectName + "::presentation::controllers\n";
     s += "{\n";
     s += "  void HomeController::register_routes(vix::App &app)\n";
@@ -65,33 +95,62 @@ namespace vix::commands::new_cmd::templates
 
   std::string make_backend_health_controller_hpp(const std::string &projectName)
   {
+    const std::string guard = make_backend_header_guard(projectName, "HEALTH_CONTROLLER");
+
     std::string s;
-    s.reserve(800);
+    s.reserve(1700);
+
+    s += "/**\n";
+    s += " * @file HealthController.hpp\n";
+    s += " * @brief Health check routes for the " + projectName + " backend.\n";
+    s += " */\n\n";
+
+    s += "#ifndef " + guard + "\n";
+    s += "#define " + guard + "\n\n";
 
-    s += "#pragma once\n\n";
     s += "namespace vix\n";
     s += "{\n";
     s += "  class App;\n";
     s += "}\n\n";
+
     s += "namespace " + projectName + "::presentation::controllers\n";
     s += "{\n";
+    s += "  /**\n";
+    s += "   * @brief Registers health check routes for the backend application.\n";
+    s += "   *\n";
+    s += "   * HealthController exposes routes intended for local checks, reverse\n";
+    s += "   * proxies, deployment scripts, and production monitoring.\n";
+    s += "   */\n";
     s += "  class HealthController\n";
     s += "  {\n";
     s += "  public:\n";
+    s += "    /**\n";
+    s += "     * @brief Register health check routes on the given Vix application.\n";
+    s += "     *\n";
+    s += "     * @param app Target application receiving the routes.\n";
+    s += "     */\n";
     s += "    static void register_routes(vix::App &app);\n";
     s += "  };\n";
-    s += "} // namespace " + projectName + "::presentation::controllers\n";
+    s += "} // namespace " + projectName + "::presentation::controllers\n\n";
+
+    s += "#endif // " + guard + "\n";
 
     return s;
   }
 
   std::string make_backend_health_controller_cpp(const std::string &projectName)
   {
     std::string s;
-    s.reserve(1700);
+    s.reserve(2600);
+
+    s += "/**\n";
+    s += " * @file HealthController.cpp\n";
+    s += " * @brief Health route implementation for the " + projectName + " backend.\n";
+    s += " */\n\n";
 
     s += "#include <" + projectName + "/presentation/controllers/HealthController.hpp>\n\n";
     s += "#include <vix.hpp>\n\n";
+
     s += "namespace " + projectName + "::presentation::controllers\n";
     s += "{\n";
     s += "  void HealthController::register_routes(vix::App &app)\n";
@@ -105,6 +164,7 @@ namespace vix::commands::new_cmd::templates
     s += "        \"service\", \"" + projectName + "\"\n";
     s += "      });\n";
     s += "    });\n\n";
+
     s += "    app.get(\"/api/health\", [](vix::Request &req, vix::Response &res)\n";
     s += "    {\n";
     s += "      (void)req;\n\n";