Apx

Quick Start

The project follows standard apx conventions. Use MCP tools and pattern files instead of exploring the codebase:

1. routes — Call this first to see all API routes. Do NOT read source files to explore.
2. docs — Search SDK docs for the method you need (e.g. "jobs list") before writing any ws.* call.
3. Follow patterns — See backend-patterns.md for models, routers, pagination, and DI.
4. refresh_openapi — Run after adding/modifying backend routes so frontend hooks update automatically.
5. check — Run type checks to verify correctness after changes.

Project Structure

src/<app>/
├── ui/                    # React + Vite frontend
│   ├── components/        # UI components (shadcn/ui)
│   ├── routes/            # @tanstack/react-router pages
│   ├── lib/               # Utilities (api client, selector)
│   └── styles/            # CSS styles
└── backend/               # FastAPI backend
    ├── app.py             # Main FastAPI app
    ├── router.py          # API routes
    ├── models.py          # Pydantic models
    └── core.py            # Config, logging, Dependency class, bootstrap

CLI Commands

Addons

Addons extend the base project with additional capabilities (UI, assistant rules, database integrations, etc.). To list available addons, run apx dev apply --help. To apply an addon to an existing project: apx dev apply <addon> (e.g. apx dev apply lakebase). During apx init, addons are selected interactively or via --addons=ui,claude,sidebar.

Adding to an Existing Project

Use --as-member to add apx into an existing Python project or monorepo as a uv workspace member:

# Recommended: explicit member path
apx init --as-member=packages/app

# Or just auto-detect (when pyproject.toml exists without [tool.apx])
apx init

Auto-detected: running apx init in a directory with an existing pyproject.toml (without [tool.apx]) automatically uses member mode with default path packages/app.

The command:

• Creates app files in the member subdirectory (e.g. packages/app)
• Configures [tool.uv.workspace] in the root pyproject.toml
• Initializes git at the workspace root if needed

MCP Tools

When the apx MCP server is running, these tools are available:

Recommended Workflow

1. routes — List all API routes to understand the project's API surface
2. get_route_info — Get a complete code example for a specific route
3. search_registry_components / add_component — Find and install UI components
4. refresh_openapi — Regenerate the API client after backend route changes
5. check — Run type checks to verify correctness
6. start / restart — Start or restart the dev server to test changes
7. logs — Diagnose runtime errors if something goes wrong

Do's and Don'ts

• OpenAPI client auto-regenerates on code changes when dev servers are running — don't manually regenerate.
• Prefer running apx related commands via MCP server if it's available.
• Use the apx MCP search_registry_components and add_component tools to find and add shadcn/ui components.
• When using the API calls on the frontend, use error boundaries to handle errors.
• Run apx dev check command (via CLI or MCP) to check for errors in the project code after making changes.
• If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright MCP to automate browser actions.

Databricks SDK

• SDK first: Always use databricks-sdk (WorkspaceClient) methods for Databricks operations. Never use raw requests/httpx calls or ws.api_client.do() to call Databricks REST APIs.
• Verify signatures: Call the docs MCP tool before writing any ws.* call to confirm the exact method name, parameters, and return type.
• SDK listing methods (e.g. ws.jobs.list(), ws.clusters.list()) return lazy iterators that auto-paginate — do NOT manually manage API pagination tokens when calling SDK methods.
• SDK dataclasses are Pydantic-compatible — use them directly in response_model or compose into custom models: class MyResponse(BaseModel): payload: SdkDataclass.
• Inject the WorkspaceClient via Dependencies.Client (service principal) or Dependencies.UserClient (OBO) — never construct it manually.
• For paginated list endpoints, see Backend Patterns — SDK Listing with Pagination.

Package Management

• Frontend: Use apx bun install or apx bun add <dependency> for frontend package management.
• Python: Always use uv (never pip).

Component Management

• Check configured registries first: Before creating custom components, check [tool.apx.ui.registries] in pyproject.toml for domain-specific registries (e.g. @ai-elements for chat/AI components, @animate-ui for animations). Use list_registry_components with the registry name to browse all available components.
• Finding components: Use MCP search_registry_components to search across all registries. Results from project-configured registries are boosted in scoring.
• Adding components: Use MCP add_component or CLI apx components add <component> --yes. For custom registries: @registry-name/component-name.
• Component location: If a component was added to a wrong location (e.g. src/components/ instead of src/<app>/ui/components/), move it to the proper folder.
• Component organization: Group components by functionality (e.g. src/<app>/ui/components/chat/).

Reference Files

For detailed patterns and code examples, see:

• Backend Patterns — DI, 3-model pattern, CRUD routers, lifespan, AppConfig
• Frontend Patterns — Suspense, mutations, selector, component conventions

Resources

• OpenAPI client: src/<app>/ui/lib/api.ts (auto-generated). Example:

  import { api } from "@/lib/api";
  

• Selector: src/<app>/ui/lib/selector.ts Example:

  import { selector } from "@/lib/selector";
  

• Routes: src/<app>/ui/routes/
• Components: src/<app>/ui/components/
• Backend: src/<app>/backend/