### Install Project Dependencies

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/src/js/web/README.md

Run these commands to install project dependencies and start the development server.

```bash
npm install
npm run start
```

--------------------------------

### Start Local Development Environment

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/README.md

These commands initiate the local development setup, including infrastructure, database upgrades, and running the application. A `.env` file is required.

```bash
cp .env.local.example .env
. .venv/bin/activate
make start-infra
app database upgrade
app run
```

--------------------------------

### Copy Example Environment File

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/usage/installation.rst

Copy the example .env file to create your local environment configuration. Ensure important settings like SECRET_KEY and DATABASE_URL are set.

```bash
cp .env.local.example .env
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/CONTRIBUTING.rst

Use `uv sync --all-groups` to create a virtual environment and install all necessary project dependencies.

```console
uv sync --all-groups
```

--------------------------------

### Run Development Environment with Docker Compose

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/README.md

Execute this command to start the complete development environment in a containerized setup. Ensure Docker is installed and configured.

```bash
docker compose up
```

--------------------------------

### Install Documentation Dependencies

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/CONTRIBUTING.rst

If you are working on the documentation, install the extra dependencies using `uv sync --group docs`.

```console
uv sync --group docs
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/CONTRIBUTING.rst

Install pre-commit hooks to ensure code quality and formatting before committing changes. Run `pre-commit install` after installing pre-commit.

```console
pre-commit install
```

--------------------------------

### Install Development Environment

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/usage/development.rst

Use this command to remove any existing environment and install a new one with the latest dependencies.

```shell
make install
```

--------------------------------

### Install Dependencies and Activate Virtual Environment

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/README.md

Run these commands to set up the development environment. Ensure you have a virtual environment activated before proceeding.

```shell
make install
. .venv/bin/activate
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/CONTRIBUTING.rst

After installing documentation dependencies, serve the documentation locally using `make docs-serve`.

```console
make docs-serve
```

--------------------------------

### Build Documentation Locally

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/CONTRIBUTING.rst

Build the project documentation locally using the `make docs` command after installing the necessary dependencies.

```console
make docs
```

--------------------------------

### Install React-Query Dependencies

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/src/js/web/README.md

Add React-Query and its devtools to your project using npm.

```bash
npm install @tanstack/react-query @tanstack/react-query-devtools
```

--------------------------------

### TanStack Router Root Layout Example

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/src/js/web/README.md

This example demonstrates a root layout component for TanStack Router. It includes navigation links for 'Home' and 'About', an Outlet for rendering child routes, and the TanStack Router Devtools. The layout is defined in 'src/routes/__root.tsx'.

```tsx
import { Outlet, createRootRoute } from '@tanstack/react-router'
import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'

import { Link } from "@tanstack/react-router";

export const Route = createRootRoute({
  component: () => (
    <>
      <header>
        <nav>
          <Link to="/">Home</Link>
          <Link to="/about">About</Link>
        </nav>
      </header>
      <Outlet />
      <TanStackRouterDevtools />
    </>
  ),
})
```

--------------------------------

### Initiate MFA Setup

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Generates a Time-based One-Time Password (TOTP) secret and a QR code for setting up an authenticator app. This is the first step in enabling MFA.

```bash
curl -X POST "http://localhost:8000/api/mfa/enable" \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Build Frontend Assets

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/usage/startup.rst

Builds the frontend assets for production deployment. This command should be run before starting the production server.

```bash
uv run app assets build
```

--------------------------------

### Confirm MFA Setup

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Confirms the Multi-Factor Authentication (MFA) setup by providing a valid TOTP code. Upon successful confirmation, it returns backup recovery codes.

```bash
curl -X POST "http://localhost:8000/api/mfa/confirm" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'
```

--------------------------------

### Run Development Server

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/usage/startup.rst

Starts the Litestar API, SAQ workers, and the Vite dev server. Ensure VITE_DEV_MODE is set to true. Assets are served under /static/web/.

```bash
uv run app run
```

--------------------------------

### Integrate aiosql, SQLAlchemy, and Litestar

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/changelog.rst

Provides an example of integrating aiosql, SQLAlchemy, and Litestar for database operations.

```python
from litestar import Litestar
from litestar.contrib.sqlalchemy.asyncio import SQLAlchemyAsyncConfig
from litestar.contrib.sqlalchemy.plugins import SQLAlchemyPlugin
from sqlalchemy.ext.asyncio import create_async_engine


class User(Base):
    __tablename__ = "user"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(50))
    fullname: Mapped[Optional[str]] = mapped_column(String(50), nullable=True)

    addresses: Mapped[List["Address"]] = relationship(back_populates="user")


class Address(Base):
    __tablename__ = "address"

    id: Mapped[int] = mapped_column(primary_key=True)
    email: Mapped[str] = mapped_column(String(50), nullable=False)
    user_id: Mapped[int] = mapped_column(ForeignKey("user.id"))

    user: Mapped["User"] = relationship(back_populates="addresses")


app = Litestar(
    plugins=[
        SQLAlchemyPlugin(config=SQLAlchemyAsyncConfig(engine_config=EngineConfig(url="sqlite+aiosqlite:///./db.sqlite")))
    ]
)

```

--------------------------------

### Install TanStack Store Dependency

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/src/js/web/README.md

Add TanStack Store to your project dependencies using npm.

```bash
npm install @tanstack/store
```

--------------------------------

### TanStack Router Route with Data Loader

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/src/js/web/README.md

This example shows how to define a route with a data loader using TanStack Router. The 'loader' function fetches data from the SWAPI API before the route component renders. The fetched data is then used to display a list of people. Ensure the 'rootRoute' is correctly defined elsewhere.

```tsx
const peopleRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: "/people",
  loader: async () => {
    const response = await fetch("https://swapi.dev/api/people");
    return response.json() as Promise<{ 
      results: { 
        name: string;
      }[];
    }>;
  },
  component: () => {
    const data = peopleRoute.useLoaderData();
    return (
      <ul>
        {data.results.map((person) => (
          <li key={person.name}>{person.name}</li>
        ))}
      </ul>
    );
  },
});
```

--------------------------------

### Get Team Details

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Retrieves details for a specific team. Requires team membership.

```bash
curl -X GET "http://localhost:8000/api/teams/770e8400-e29b-41d4-a716-446655440002" \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Get MFA Status

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Retrieves the current Multi-Factor Authentication (MFA) configuration status for the authenticated user.

```bash
curl -X GET "http://localhost:8000/api/mfa/status" \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Create SPA Navigation Link

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/src/js/web/README.md

Import and use the Link component from '@tanstack/react-router' for Single Page Application navigation. This example creates a link to the '/about' route.

```tsx
import { Link } from "@tanstack/react-router";

<Link to="/about">About</Link>
```

--------------------------------

### Get Current User Profile

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Retrieves the profile information for the currently authenticated user. Requires an Authorization header with a valid Bearer token.

```bash
curl -X GET "http://localhost:8000/api/me" \
  -H "Authorization: Bearer <access_token>"
```

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "name": "John Doe",
  "is_active": true,
  "is_verified": true,
  "is_superuser": false,
  "created_at": "2024-01-01T00:00:00Z",
  "teams": [
    {"id": "team-uuid", "name": "Engineering"}
  ],
  "roles": [
    {"id": "role-uuid", "name": "Member"}
  ]
}
```

--------------------------------

### Get OAuth Provider Availability

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Retrieve the status of configured OAuth providers (e.g., Google, GitHub) to inform frontend authentication options.

```bash
curl -X GET "http://localhost:8000/api/config/oauth"
```

```json
# Response:
{
  "google_enabled": true,
  "github_enabled": true
}
```

--------------------------------

### Set up React-Query Client and Provider

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/src/js/web/README.md

Initialize a QueryClient and wrap your application with QueryClientProvider in main.tsx.

```tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

// ...

const queryClient = new QueryClient();

// ...

if (!rootElement.innerHTML) {
  const root = ReactDOM.createRoot(rootElement);

  root.render(
    <QueryClientProvider client={queryClient}>
      <RouterProvider router={router} />
    </QueryClientProvider>
  );
}
```

--------------------------------

### Build Project for Production

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/src/js/web/README.md

Execute this command to create a production-ready build of the application.

```bash
npm run build
```

--------------------------------

### Create Default Application Roles via CLI

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Initialize the application with pre-defined roles and assign them to users.

```bash
app users create-roles
```

--------------------------------

### Create New User via CLI

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Create a new user account using the command-line interface. Supports interactive mode or specifying user details as options.

```bash
# Interactive mode
app users create-user
```

```bash
# With options
app users create-user --email admin@example.com --name "Admin User" --password "SecurePass123!" --superuser
```

--------------------------------

### Create User (Admin)

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Creates a new user account in the system. Requires superuser privileges.

```bash
curl -X POST "http://localhost:8000/api/users" \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "name": "New User",
    "password": "SecurePassword123!",
    "is_superuser": false
  }'
```

--------------------------------

### Execute Full Test Suite

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/usage/development.rst

Run this command to execute all tests for the project.

```shell
make test
```

--------------------------------

### Fetch Data with useQuery

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/src/js/web/README.md

Use the useQuery hook to fetch and manage data, providing a queryKey and queryFn. Initial data can be provided.

```tsx
import { useQuery } from "@tanstack/react-query";

import "./App.css";

function App() {
  const { data } = useQuery({
    queryKey: ["people"],
    queryFn: () =>
      fetch("https://swapi.dev/api/people")
        .then((res) => res.json())
        .then((data) => data.results as { name: string }[]),
    initialData: [],
  });

  return (
    <div>
      <ul>
        {data.map((person) => (
          <li key={person.name}>{person.name}</li>
        ))}
      </ul>
    </div>
  );
}

export default App;
```

--------------------------------

### Create Tag

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Creates a new tag. Requires superuser privileges.

```bash
curl -X POST "http://localhost:8000/api/tags" \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "frontend",
    "description": "Frontend development"
  }'
```

--------------------------------

### Upgrade Project Dependencies

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/usage/development.rst

This command upgrades all application components simultaneously, including uv, bun, and pre-commit.

```shell
make upgrade
```

--------------------------------

### User Registration

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Creates a new user account with email, name, and password. Sends a verification email upon successful creation. Requires JSON payload with user credentials.

```bash
curl -X POST "http://localhost:8000/api/access/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "name": "New User",
    "password": "SecurePassword123!"
  }'
```

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "newuser@example.com",
  "name": "New User",
  "is_active": true,
  "is_verified": false,
  "is_superuser": false,
  "created_at": "2024-01-15T10:30:00Z"
}
```

--------------------------------

### Database Management Commands

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

CLI commands for managing the application's database, including migrations, resets, and running the application.

```bash
# Run database migrations
app database upgrade
```

```bash
# Reset database (development only)
app database reset
```

```bash
# Run application
app run
```

--------------------------------

### List Users (Admin)

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Lists all users in the system with support for pagination, filtering, and searching. Requires superuser privileges.

```bash
curl -X GET "http://localhost:8000/api/users?limit=10&offset=0&search=john" \
  -H "Authorization: Bearer <admin_access_token>"
```

--------------------------------

### Execute Pre-commit Hooks

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/usage/development.rst

Run this command to automatically execute the project's pre-commit process for linting and code quality checks.

```shell
make lint
```

--------------------------------

### Serve SAQ UI through Litestar

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/changelog.rst

Integrates the SAQ (Simple Async Queue) web UI within a Litestar application. This commit also includes fixes for dict tracebacks and linting changes.

```python
from litestar import Litestar
from litestar.contrib.saq import SaqManager


app = Litestar(route_handlers=[SaqManager()])

```

--------------------------------

### Run Project Tests

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/src/js/web/README.md

Use this command to run all project tests using Vitest.

```bash
npm run test
```

--------------------------------

### Create Team Invitation

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Sends an invitation to a user to join a team. Requires team membership.

```bash
curl -X POST "http://localhost:8000/api/teams/770e8400-e29b-41d4-a716-446655440002/invitations" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "invitee@example.com",
    "role": "member"
  }'
```

--------------------------------

### Full Makefile Contents

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/usage/development.rst

This dropdown reveals the complete Makefile used for development tasks in the repository.

```make
#!make

# Project
PROJECT_NAME := litestar-fullstack

# Python
PYTHON := python3

# Bun
BUN := bun

# Uvicorn
UVICORN := uvicorn

# Uvicorn
UV := uv

# Pre-commit
PRE_COMMIT := pre-commit

# Docker

# Build
build:
	$(PYTHON) -m poetry build

# Install
install:
	@echo "Installing development environment..."
	@$(PYTHON) -m poetry install --with dev
	@$(PYTHON) -m poetry run pre-commit install
	@echo "Development environment installed."

# Upgrade
upgrade:
	@echo "Upgrading project dependencies..."
	@$(UV) lock --upgrade
	@$(BUN) update
	@$(PRE_COMMIT) autoupdate
	@echo "Project dependencies upgraded."

# Lint
lint:
	@echo "Running pre-commit hooks..."
	@$(PRE_COMMIT) run --all-files
	@echo "Pre-commit hooks passed."

# Test
test:
	@echo "Running tests..."
	@$(PYTHON) -m poetry run pytest
	@echo "Tests passed."

# Type generation
types:
	@echo "Generating TypeScript types..."
	@$(PYTHON) -m poetry run litestar-fullstack generate types
	@echo "TypeScript types generated."

# Database
database:
	@echo "Running database commands..."

	@$(UV) run app database make-migrations
	@$(UV) run app database upgrade
	@echo "Database commands executed."

# Run
run:
	@echo "Starting development server..."
	@$(PYTHON) -m poetry run uvicorn app.main:app --reload --port 8000

# Clean
clean:
	@echo "Cleaning project..."
	@rm -rf dist build *.egg-info
	@rm -rf .venv
	@echo "Project cleaned."

.PHONY:
	build
	install
	upgrade
	lint
	test
	types
	database
	run
	clean

```

--------------------------------

### Run Linters and Formatters

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/CONTRIBUTING.rst

Optionally, run linters and formatters across all files using `pre-commit run --all-files` before committing. This step is also executed automatically before commits.

```console
pre-commit run --all-files
```

--------------------------------

### Promote User to Superuser via CLI

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Grant superuser privileges to an existing user by specifying their email address.

```bash
app users promote-to-superuser --email user@example.com
```

--------------------------------

### Create User Management Command

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/changelog.rst

Adds a management command to create new users via the CLI. Requires superuser access for User Account CRUD routes.

```python
poetry run app manage promote-to-superuser --email example@string.com
```

```python
poetry run app manage create-user
```

--------------------------------

### Create Team

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Creates a new team. The current user automatically becomes the owner of the newly created team.

```bash
curl -X POST "http://localhost:8000/api/teams" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Project Team",
    "description": "Team for the new project"
  }'
```

--------------------------------

### Generate New Database Migrations

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/usage/development.rst

Create a new database migration file using the Litestar CLI.

```shell
uv run app database make-migrations
```

--------------------------------

### Call Litestar CLI from Click App

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/changelog.rst

Demonstrates how to call the Litestar CLI from another Click application.

```python
from litestar.cli.core import cli


@app.command()
def hello_world() -> None:
    """Says hello world."""
    print("hello world")


if __name__ == "__main__":
    cli.add_command(app)
    cli()

```

--------------------------------

### Lint and Format Code

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/src/js/web/README.md

These scripts use Biome for linting and formatting. Run 'npm run lint' to check code quality, 'npm run format' to format code, and 'npm run check' to perform both linting and formatting checks.

```bash
npm run lint
npm run format
npm run check
```

--------------------------------

### Add Shadcn Component

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/src/js/web/README.md

Use this command to add components from Shadcn UI to your project. Replace 'button' with the desired component name.

```bash
pnpx shadcn@latest add button
```

--------------------------------

### System API - OAuth Configuration

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Returns OAuth provider availability for frontend configuration.

```APIDOC
## GET /api/config/oauth

### Description
Returns OAuth provider availability for frontend configuration.

### Method
GET

### Endpoint
/api/config/oauth

### Response
#### Success Response (200)
- **google_enabled** (boolean) - Indicates if Google OAuth is enabled.
- **github_enabled** (boolean) - Indicates if GitHub OAuth is enabled.

#### Response Example
```json
{
  "google_enabled": true,
  "github_enabled": true
}
```
```

--------------------------------

### Create a Derived State Store

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/src/js/web/README.md

Implement derived state by creating a new store that depends on another store's state. Ensure the derived store is mounted.

```tsx
import { useStore } from "@tanstack/react-store";
import { Store, Derived } from "@tanstack/store";
import "./App.css";

const countStore = new Store(0);

const doubledStore = new Derived({
  fn: () => countStore.state * 2,
  deps: [countStore],
});
doubledStore.mount();

function App() {
  const count = useStore(countStore);
  const doubledCount = useStore(doubledStore);

  return (
    <div>
      <button onClick={() => countStore.setState((n) => n + 1)}>
        Increment - {count}
      </button>
      <div>Doubled - {doubledCount}</div>
    </div>
  );
}

export default App;
```

--------------------------------

### Login - Authenticate User

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Authenticates a user with email and password. Returns JWT access tokens or initiates an MFA challenge if enabled. Requires username and password in form-urlencoded format.

```bash
curl -X POST "http://localhost:8000/api/access/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=user@example.com&password=securepassword123"
```

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": null
}
```

```json
{
  "mfa_required": true,
  "message": "MFA verification required"
}
# Note: MFA challenge token is set in httpOnly cookie
```

--------------------------------

### CLI Commands - Database Management

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Commands for managing the application database.

```APIDOC
## CLI Commands - Database Management

### Run Database Migrations

Applies pending database migrations.

#### Usage
```bash
app database upgrade
```

### Reset Database

Resets the database. **Caution**: This command is intended for development environments only.

#### Usage
```bash
app database reset
```

### Run Application

Starts the application server.

#### Usage
```bash
app run
```
```

--------------------------------

### Cryptography Module Overview

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/api/lib/crypt.rst

Provides an overview of the cryptography-related functionalities available in the `app.lib.crypt` module.

```APIDOC
## Cryptography Configuration

### Description
This section covers the configuration and usage of cryptographic utilities within the Litestar application. It pertains to the `app.lib.crypt` module, detailing its members and functionalities.

### Module
`app.lib.crypt`

### Members
This module exposes various members related to application cryptography. Refer to the specific documentation for each member for detailed usage instructions.
```

--------------------------------

### Upgrade Database to Latest Revision

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/usage/development.rst

Apply the latest database schema changes by upgrading to the most recent revision.

```shell
uv run app database upgrade
```

--------------------------------

### List Tags

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Retrieves a list of tags, supporting pagination and search. Requires authentication.

```bash
curl -X GET "http://localhost:8000/api/tags?search=tech&limit=20" \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Check System Health

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Use this endpoint to verify the health status of the application and its database connectivity. Responses vary based on database status.

```bash
curl -X GET "http://localhost:8000/health"
```

```json
# Response (healthy):
{
  "database_status": "online",
  "app": "litestar-fullstack"
}
```

```json
# Response (unhealthy - returns 500):
{
  "database_status": "offline",
  "app": "litestar-fullstack"
}
```

--------------------------------

### List Teams

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Lists teams that the current user has access to. Supports pagination.

```bash
curl -X GET "http://localhost:8000/api/teams?limit=20&offset=0" \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### CLI Commands - User Management

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Commands for managing users via the command line interface.

```APIDOC
## CLI Commands - User Management

### Create User

Creates a new user via command line.

#### Usage
```bash
# Interactive mode
app users create-user

# With options
app users create-user --email admin@example.com --name "Admin User" --password "SecurePass123!" --superuser
```

### Promote to Superuser

Promotes an existing user to superuser status.

#### Usage
```bash
app users promote-to-superuser --email user@example.com
```

### Create Default Roles

Creates pre-configured application roles and assigns them to users.

#### Usage
```bash
app users create-roles
```
```

--------------------------------

### Create a Simple Counter Store

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/src/js/web/README.md

Define a basic counter store using the Store class and use the useStore hook to access its state in a React component.

```tsx
import { useStore } from "@tanstack/react-store";
import { Store } from "@tanstack/store";
import "./App.css";

const countStore = new Store(0);

function App() {
  const count = useStore(countStore);
  return (
    <div>
      <button onClick={() => countStore.setState((n) => n + 1)}>
        Increment - {count}
      </button>
    </div>
  );
}

export default App;
```

--------------------------------

### List Team Invitations

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Retrieves a list of pending invitations for a specific team. Requires team membership.

```bash
curl -X GET "http://localhost:8000/api/teams/770e8400-e29b-41d4-a716-446655440002/invitations" \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### deps Module Documentation

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/api/lib/deps.rst

This snippet contains the auto-generated documentation for the app.lib.deps module, detailing its members and functionalities.

```APIDOC
## Documentation for the deps module

This documentation covers the members and functionalities of the `app.lib.deps` module.

### Module
`app.lib.deps`

### Members

(Detailed documentation for each member of the module would follow here, extracted from the automodule directive.)
```

--------------------------------

### Accept Team Invitation

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Accepts a pending team invitation. The request must be made by the invited user.

```bash
curl -X POST "http://localhost:8000/api/teams/770e8400-e29b-41d4-a716-446655440002/invitations/990e8400-e29b-41d4-a716-446655440004/accept" \
  -H "Authorization: Bearer <invitee_access_token>"
```

--------------------------------

### List Active Sessions

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Retrieves a list of all active sessions for the currently authenticated user.

```bash
curl -X GET "http://localhost:8000/api/access/sessions" \
  -H "Authorization: Bearer <access_token>"
```

--------------------------------

### Generate Secret Key

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/usage/installation.rst

Use openssl to generate a secure random base64 encoded secret key for your application's security settings.

```bash
openssl rand -base64 32
```

--------------------------------

### Add React Query Devtools

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/src/js/web/README.md

Optionally include React Query Devtools in your root route component for debugging.

```tsx
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";

const rootRoute = createRootRoute({
  component: () => (
    <>
      <Outlet />
      <ReactQueryDevtools buttonPosition="top-right" />
      <TanStackRouterDevtools />
    </>
  ),
});
```

--------------------------------

### Update User (Admin)

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Updates an existing user's details. Requires superuser privileges.

```bash
curl -X PATCH "http://localhost:8000/api/users/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <admin_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'
```

--------------------------------

### User Management API (Admin)

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Endpoints for administrative user management, including listing, creating, updating, and deleting users.

```APIDOC
## GET /api/users

### Description
Lists all users with pagination, filtering, and search capabilities. Requires superuser privileges.

### Method
GET

### Endpoint
/api/users

### Query Parameters
- **limit** (integer) - Optional - The maximum number of users to return.
- **offset** (integer) - Optional - The number of users to skip.
- **search** (string) - Optional - A search term to filter users by.

### Response
#### Success Response (200)
- **items** (array of objects) - A list of user objects.
  - **id** (string) - The unique identifier of the user.
  - **email** (string) - The email address of the user.
  - **name** (string) - The name of the user.
  - **is_active** (boolean) - Whether the user account is active.
  - **is_verified** (boolean) - Whether the user's email has been verified.
  - **is_superuser** (boolean) - Whether the user has superuser privileges.
  - **created_at** (string) - The timestamp when the user was created.
- **total** (integer) - The total number of users matching the query.
- **limit** (integer) - The limit applied to the query.
- **offset** (integer) - The offset applied to the query.

#### Response Example
```json
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "john@example.com",
      "name": "John Doe",
      "is_active": true,
      "is_verified": true,
      "is_superuser": false,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}
```
```

```APIDOC
## POST /api/users

### Description
Creates a new user account. Requires superuser privileges.

### Method
POST

### Endpoint
/api/users

### Request Body
- **email** (string) - Required - The email address for the new user.
- **name** (string) - Required - The name of the new user.
- **password** (string) - Required - The password for the new user.
- **is_superuser** (boolean) - Optional - Whether the new user should have superuser privileges.

### Request Example
```json
{
  "email": "newuser@example.com",
  "name": "New User",
  "password": "SecurePassword123!",
  "is_superuser": false
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the newly created user.
- **email** (string) - The email address of the new user.
- **name** (string) - The name of the new user.
- **is_active** (boolean) - Whether the new user account is active.
- **is_verified** (boolean) - Whether the new user's email has been verified.
- **is_superuser** (boolean) - Whether the new user has superuser privileges.

#### Response Example
```json
{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "email": "newuser@example.com",
  "name": "New User",
  "is_active": true,
  "is_verified": false,
  "is_superuser": false
}
```
```

```APIDOC
## PATCH /api/users/{user_id}

### Description
Updates an existing user's details. Requires superuser privileges.

### Method
PATCH

### Endpoint
/api/users/{user_id}

### Path Parameters
- **user_id** (string) - Required - The ID of the user to update.

### Request Body
- **is_active** (boolean) - Optional - Set to `false` to deactivate the user.

### Request Example
```json
{
  "is_active": false
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the updated user.
- **email** (string) - The email address of the user.
- **name** (string) - The name of the user.
- **is_active** (boolean) - The updated active status of the user.

#### Response Example
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "john@example.com",
  "name": "John Doe",
  "is_active": false
}
```
```

```APIDOC
## DELETE /api/users/{user_id}

### Description
Deletes a user from the system. Requires superuser privileges.

### Method
DELETE

### Endpoint
/api/users/{user_id}

### Path Parameters
- **user_id** (string) - Required - The ID of the user to delete.

### Response
#### Success Response (204)
No Content.
```

--------------------------------

### Update Team Details

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Updates the details of an existing team. Requires team admin role.

```bash
curl -X PATCH "http://localhost:8000/api/teams/770e8400-e29b-41d4-a716-446655440002" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated engineering team description"}'
```

--------------------------------

### Delete User (Admin)

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Deletes a user from the system. Requires superuser privileges. This operation returns a 204 No Content status on success.

```bash
curl -X DELETE "http://localhost:8000/api/users/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <admin_access_token>"
```

--------------------------------

### Msgspec Handlers with Additional Serializers

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/changelog.rst

Enhances Makefile configurations by adding additional serializers to the msgspec handlers for improved data serialization.

```python
from litestar.contrib.msgspec import MsgspecProtocol


class CustomProtocol(MsgspecProtocol):
    def default_deserializer(self, data: bytes) -> Any:
        return msgspec.msgpack.decode(data)

    def default_serializer(self, data: Any) -> bytes:
        return msgspec.msgpack.encode(data)


app = Litestar(protocol_stack=[CustomProtocol()])

```

--------------------------------

### Application Exceptions

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/api/lib/exceptions.rst

This section covers the custom exceptions defined in the application's exception module.

```APIDOC
## Application Exceptions

### Description
This module contains custom exception classes designed for application-specific error handling.

### Module
`app.lib.exceptions`

### Members
This module exposes various exception classes that can be raised and handled throughout the application.

* **`HTTPException`**: Base class for HTTP-related exceptions.
* **`NotFoundException`**: Raised when a requested resource is not found.
* **`BadRequestException`**: Raised when the client sends an invalid request.
* **`UnauthorizedException`**: Raised when authentication fails.
* **`ForbiddenException`**: Raised when the authenticated user lacks permissions.
* **`InternalServerException`**: Raised for unexpected server errors.
* **`ConflictException`**: Raised when the request conflicts with the current state of the resource.
* **`UnprocessableEntityException`**: Raised when the request is well-formed but contains semantic errors.

### Usage Example
```python
from app.lib.exceptions import NotFoundException

def get_item(item_id: int):
    if not item_exists(item_id):
        raise NotFoundException(f"Item with id {item_id} not found")
    # ... return item
```
```

--------------------------------

### Authentication API

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Endpoints for user authentication, including login, logout, token refresh, registration, and password reset.

```APIDOC
## POST /api/access/login

### Description
Authenticates a user with email and password. Returns JWT access tokens or an MFA challenge if two-factor authentication is enabled.

### Method
POST

### Endpoint
/api/access/login

### Parameters
#### Query Parameters
- **username** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.

### Request Example
```bash
curl -X POST "http://localhost:8000/api/access/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=user@example.com&password=securepassword123"
```

### Response
#### Success Response (200)
- **access_token** (string) - The JWT access token.
- **token_type** (string) - The type of token, usually 'bearer'.
- **expires_in** (integer) - The token's expiration time in seconds.
- **refresh_token** (string) - The refresh token (null if not applicable).

#### MFA Required Response (401)
- **mfa_required** (boolean) - Indicates if MFA is required.
- **message** (string) - Message indicating MFA verification is needed.

#### Response Example (No MFA)
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": null
}
```

#### Response Example (MFA Required)
```json
{
  "mfa_required": true,
  "message": "MFA verification required"
}
```
```

```APIDOC
## POST /api/access/logout

### Description
Revokes the current refresh token family and clears authentication cookies.

### Method
POST

### Endpoint
/api/access/logout

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
#### Cookies
- **refresh_token** (string) - Required - The user's refresh token.

### Request Example
```bash
curl -X POST "http://localhost:8000/api/access/logout" \
  -H "Authorization: Bearer <access_token>" \
  --cookie "refresh_token=<refresh_token>"
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "OK"
}
```
```

```APIDOC
## POST /api/access/refresh

### Description
Refreshes the access token using a refresh token cookie. Implements token rotation for security.

### Method
POST

### Endpoint
/api/access/refresh

### Parameters
#### Cookies
- **refresh_token** (string) - Required - The user's refresh token.

### Request Example
```bash
curl -X POST "http://localhost:8000/api/access/refresh" \
  --cookie "refresh_token=<refresh_token>"
```

### Response
#### Success Response (200)
- **access_token** (string) - The new JWT access token.
- **token_type** (string) - The type of token, usually 'bearer'.
- **expires_in** (integer) - The token's expiration time in seconds.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}
```
```

```APIDOC
## POST /api/access/signup

### Description
Creates a new user account and sends a verification email.

### Method
POST

### Endpoint
/api/access/signup

### Parameters
#### Request Body
- **email** (string) - Required - The user's email address.
- **name** (string) - Required - The user's full name.
- **password** (string) - Required - The user's desired password.

### Request Example
```bash
curl -X POST "http://localhost:8000/api/access/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "name": "New User",
    "password": "SecurePassword123!"
  }'
```

### Response
#### Success Response (201)
- **id** (string) - The unique identifier for the new user.
- **email** (string) - The user's email address.
- **name** (string) - The user's full name.
- **is_active** (boolean) - Indicates if the user account is active.
- **is_verified** (boolean) - Indicates if the user's email has been verified.
- **is_superuser** (boolean) - Indicates if the user has superuser privileges.
- **created_at** (string) - The timestamp when the user was created.

#### Response Example
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "newuser@example.com",
  "name": "New User",
  "is_active": true,
  "is_verified": false,
  "is_superuser": false,
  "created_at": "2024-01-15T10:30:00Z"
}
```
```

```APIDOC
## Password Reset Flow

### Description
Handles the password reset process, including requesting a reset email and completing the reset with a token.

### Method
POST (Request Reset), GET (Validate Token), POST (Complete Reset)

### Endpoints
- `/api/access/forgot-password` (Request Reset)
- `/api/access/reset-password` (Validate Token & Complete Reset)

### Request Reset
#### Description
Initiates the password reset by sending an email to the provided address.

#### Method
POST

#### Endpoint
/api/access/forgot-password

#### Parameters
##### Request Body
- **email** (string) - Required - The email address associated with the account.

#### Request Example
```bash
curl -X POST "http://localhost:8000/api/access/forgot-password" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
```

#### Response
##### Success Response (200)
- **message** (string) - Confirmation message.
- **expires_in_minutes** (integer) - The duration in minutes the reset token is valid.

##### Response Example
```json
{
  "message": "If the email exists, a password reset link has been sent",
  "expires_in_minutes": 60
}
```

### Validate Reset Token
#### Description
Validates the provided password reset token.

#### Method
GET

#### Endpoint
/api/access/reset-password

#### Parameters
##### Query Parameters
- **token** (string) - Required - The password reset token.

#### Request Example
```bash
curl -X GET "http://localhost:8000/api/access/reset-password?token=abc123def456..."
```

#### Response
##### Success Response (200)
- **valid** (boolean) - Indicates if the token is valid.
- **user_id** (string) - The ID of the user associated with the token.
- **expires_at** (string) - The expiration timestamp of the token.

##### Response Example
```json
{
  "valid": true,
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "expires_at": "2024-01-15T11:30:00Z"
}
```

### Complete Password Reset
#### Description
Completes the password reset process by setting a new password.

#### Method
POST

#### Endpoint
/api/access/reset-password

#### Parameters
##### Request Body
- **token** (string) - Required - The password reset token.
- **password** (string) - Required - The new password for the user.
- **password_confirm** (string) - Required - Confirmation of the new password.

#### Request Example
```bash
curl -X POST "http://localhost:8000/api/access/reset-password" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "abc123def456...",
    "password": "NewSecurePassword123!",
    "password_confirm": "NewSecurePassword123!"
  }'
```

#### Response
##### Success Response (200)
- **message** (string) - Confirmation message.
- **user_id** (string) - The ID of the user whose password was reset.

##### Response Example
```json
{
  "message": "Password has been successfully reset",
  "user_id": "550e8400-e29b-41d4-a716-446655440000"
}
```
```

--------------------------------

### Team Invitation Controllers

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/api/domain/teams/controllers/team_invitation.rst

Controllers for the team invitation routes for the teams domain.

```APIDOC
## Team Invitation API

### Description
This section details the API endpoints for managing team invitations.

### Method
GET, POST, PUT, DELETE (specific methods depend on implementation)

### Endpoint
/api/teams/invitations

### Parameters
(Specific parameters are not detailed in the provided text, but would typically include team ID, invitation token, user ID, etc.)

### Request Body
(Specific request body fields are not detailed in the provided text, but would typically include invitation details for POST/PUT requests.)

### Response
(Specific response fields are not detailed in the provided text, but would typically include invitation status, team details, or user information.)
```

--------------------------------

### System API - Health Check

Source: https://context7.com/litestar-org/litestar-fullstack/llms.txt

Returns system health status, including database connectivity. Returns a 500 status code if the database is offline.

```APIDOC
## GET /health

### Description
Returns system health status including database connectivity.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **database_status** (string) - The status of the database connection ('online' or 'offline').
- **app** (string) - The name of the application.

#### Response Example
```json
{
  "database_status": "online",
  "app": "litestar-fullstack"
}
```

#### Error Response (500)
- **database_status** (string) - The status of the database connection ('online' or 'offline').
- **app** (string) - The name of the application.

#### Response Example
```json
{
  "database_status": "offline",
  "app": "litestar-fullstack"
}
```
```

--------------------------------

### Accounts Domain Guards

Source: https://github.com/litestar-org/litestar-fullstack/blob/main/docs/api/domain/accounts/guards.rst

This section provides details on the guards implemented for the accounts domain.

```APIDOC
## Guards for the Accounts Domain

This module contains guards for the accounts domain.

### Module
`app.domain.accounts.guards`

### Members
This module exposes the following members:

- **`guard_function_1`** (function) - Description of guard_function_1.
- **`guard_function_2`** (function) - Description of guard_function_2.

*Note: Specific details about each guard function, such as parameters and return values, are not provided in the source text.*
```