> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tasteful.heka.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with Tasteful in 5 minutes

Welcome to Tasteful! This guide will help you create your first Tasteful application in just a few minutes. By the end, you'll have a working web API with a health check endpoint.

## Prerequisites

Before you begin, make sure you have:

* **Python 3.9 or higher** installed on your system
* **Poetry** for dependency management (recommended) or pip

<Note>
  We strongly recommend using Poetry for Python dependency management. If you don't have it installed, visit [poetry.eustace.io](https://python-poetry.org/docs/#installation) for installation instructions.
</Note>

## Step 1: Create a New Project

First, create a new directory for your project and navigate to it:

```bash theme={null}
mkdir my-tasteful-app
cd my-tasteful-app
```

## Step 2: Initialize Your Project

Initialize a new Poetry project:

```bash theme={null}
poetry init
```

Follow the interactive prompts. You can use the default values for most options. When asked about dependencies, you can skip them for now - we'll add Tasteful next.

## Step 3: Install Tasteful

Add Tasteful as a dependency to your project:

```bash theme={null}
poetry add tasteful
```

This will install Tasteful and all its required dependencies, including FastAPI and Uvicorn.

## Step 4: Create Your First Flavor

Create the basic project structure:

```bash theme={null}
mkdir app
touch app/main.py
mkdir app/flavors
mkdir app/flavors/hello_flavor.py
```

Now, let's create your first flavor. Create a file `app/flavors/hello_flavor.py`:

```python theme={null}
from tasteful.base_flavor import BaseFlavor, BaseController, BaseService
from tasteful.decorators.controller import Get


class HelloService(BaseService):
    
    def greet(self, name: str = "World"):
        """Generate a greeting message."""
        return {"message": f"Hello, {name}! Welcome to Tasteful 😋"}


class HelloController(BaseController):
    """Controller for greeting endpoints."""
    
    def __init__(self, hello_service: HelloService):
        super().__init__(prefix="/hello", tags=["greetings"])
        self.hello_service = hello_service

    @Get("/")
    def say_hello(self):
        """Say hello to the world."""
        return self.hello_service.greet()
    
    @Get("/{name}")
    def say_hello_to(self, name: str):
        """Say hello to a specific person."""
        return self.hello_service.greet(name)


class HelloFlavor(BaseFlavor):
    """A simple flavor for greeting users."""
    
    def __init__(self):
        super().__init__(
            controller=HelloController,
            services=[HelloService],
            repositories=[],  # No repositories needed for this simple example
            config=None
        )
```

## Step 5: Create Your Application

Now create your main application file in `app/main.py`:

```python theme={null}
from fastapi import FastAPI
from tasteful.tasteful_application import TastefulApp
from .flavors.hello_flavor import HelloFlavor


def create_app() -> FastAPI:
    """Create and configure the Tasteful application."""
    
    app = TastefulApp(
        title="My First Tasteful App",
        version="1.0.0",
        flavors=[
            HelloFlavor # Your custom flavor instance
        ],
        authentication_backends=[],  # No auth for now
    )
    
    return app.app


# This is what Uvicorn will look for
app = create_app()
```

## Step 6: Run Your Application

Start your development server:

```bash theme={null}
poetry run uvicorn app.main:app --reload
```

Your Tasteful application is now running! Open your browser and visit:

* [**http://127.0.0.1:8000/hello**](http://127.0.0.1:8000/hello) - Your custom greeting endpoint
* [**http://127.0.0.1:8000/hello/Alice**](http://127.0.0.1:8000/hello/Alice) - Personalized greeting
* [**http://127.0.0.1:8000/docs**](http://127.0.0.1:8000/docs) - Interactive API documentation

## Step 7: Explore the API Documentation

Tasteful automatically generates interactive API documentation powered by FastAPI. Visit [**http://127.0.0.1:8000/docs**](http://127.0.0.1:8000/docs) to see your API endpoints and test them directly in the browser.

## What You've Built

Congratulations! You've created a Tasteful application with:

* ✅ **Modular architecture** using Flavors
* ✅ **Dependency injection** with Services
* ✅ **Automatic API documentation**

## Next Steps

Now that you have a working Tasteful application, you can:

<CardGroup cols={2}>
  <Card title="Learn About Architecture" icon="building" href="/concepts/modular-architecture">
    Understand Tasteful's modular design philosophy
  </Card>

  <Card title="Explore Flavors" icon="puzzle-piece" href="/concepts/flavors">
    Deep dive into creating powerful, reusable components
  </Card>

  <Card title="Add Authentication" icon="shield-halved" href="/concepts/backends">
    Secure your application with authentication backends
  </Card>

  <Card title="Database Integration" icon="database" href="/concepts/dependency-injection">
    Connect to databases using repositories and dependency injection
  </Card>
</CardGroup>

## Troubleshooting

### Common Issues

**Port Already in Use**

* Change the port with: `uvicorn app.main:app --reload --port 8001`

**Poetry Command Not Found**

* Install Poetry from [python-poetry.org](https://python-poetry.org/docs/#installation)
* Or use pip: `pip install tasteful` (though Poetry is recommended)

### Getting Help

* **GitHub Issues**: [github.com/heka-ai/tasteful/issues](https://github.com/heka-ai/tasteful/issues)
* **Discussions**: [github.com/heka-ai/tasteful/discussions](https://github.com/heka-ai/tasteful/discussions)