Running and Developing Your Application

Once you have scaffolded your project using Castlecraft Architect and Cruft, you're ready to run its backend API and start developing your application's features. This guide covers how to run the application locally and set up debugging with Visual Studio Code.

Prerequisites

• A project scaffolded using Castlecraft Architect as described in the Scaffolding Your First Project guide.
• Your project's virtual environment activated (e.g., source .venv/bin/activate).
• Dependencies installed within your project (typically done by pip install -e . or uv pip install -e . in the project root after scaffolding).
• A .env file configured with your database connection string, as detailed in the Installation Guide (this applies to the scaffolded project's .env file).

Running the Application Manually

The backend API of your Architect-generated project is a FastAPI application. You can run it directly using Uvicorn, an ASGI server.

1. Navigate to your project's root directory:

   cd path/to/your/my_awesome_app # Replace with your project's directory

2. Ensure your virtual environment is activated:

   source .venv/bin/activate # Or .venv\Scripts\activate on Windows

3. Start the Uvicorn server: The main application instance is typically located at app_root_name.main:app within your project.

   uvicorn --host=0.0.0.0 --port=8000 --reload --log-level=debug app_root_name.main:app

   • --host=0.0.0.0: Makes the server accessible on your network. Use 127.0.0.1 for local access only.
   • --port=8000: Specifies the port to run on.
   • --reload: Enables auto-reloading when code changes are detected (very useful during development).
   • --log-level=debug: Sets the logging level to debug for more detailed output.
   • app_root_name.main:app: Points to the FastAPI application instance (app) in the main.py file inside your project's app_root_name directory.

Once started, your API should be accessible at http://0.0.0.0:8000 (or http://127.0.0.1:8000). You can typically find the auto-generated API documentation (Swagger UI) at http://0.0.0.0:8000/docs.

Running and Debugging with VS Code

Visual Studio Code provides excellent support for running and debugging Python applications. You can configure a launch.json file to easily start your Architect-generated API in debug mode.

1. Open your project folder in VS Code.

2. Create or open .vscode/launch.json: If this file doesn't exist, VS Code can help you create it. Go to the "Run and Debug" view (Ctrl+Shift+D or Cmd+Shift+D) and click on "create a launch.json file." Choose "Python" and then "FastAPI" or "Python Module" as a starting point if prompted.

3. Add the following configuration to your launch.json:

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Debug API (Architect Project)",
               "type": "debugpy",
               "request": "launch",
               "python": "${workspaceFolder}/.venv/bin/python", // Adjust if your venv is elsewhere
               "module": "uvicorn",
               "args": [
                   "--host=0.0.0.0",
                   "--port=8000",
                   "--reload",
                   "--log-level=debug",
                   "app_root_name.main:app" // Points to your project's FastAPI app
               ],
               "jinja": true // If your project uses Jinja templates
           }
           // You can also add configurations for running tests, e.g., with pytest
       ]
   }

   • "python": Ensure this path points to the Python interpreter inside your project's virtual environment.
   • "module": "uvicorn": Tells the debugger to run Uvicorn as a module.
   • "args": These are the same arguments you would pass to Uvicorn on the command line.

4. Start Debugging: Go to the "Run and Debug" view in VS Code, select "Debug API (Architect Project)" from the dropdown, and press F5 (or click the green play button). You can now set breakpoints in your Python code, inspect variables, and step through execution.

Developing Features

With your application running, you can now:

• Use the Castlecraft Architect CLI (architect revision ...) to create new components (Aggregates, Services, DTOs, etc.) within your project.
• Implement your business logic within the generated components.
• Define API endpoints (e.g., using FastAPI routers).
• Write unit and integration tests for your code.

Next Steps

Ready to get your hands dirty? Let's move on to Installation.