# App Management
Source: https://docs.fusioncat.dev/cli-reference/apps
Create and manage applications within projects
Fusioncat is currently in its alpha stage. The main API server is located at:
[https://api.staging.fusioncatalyst.io/](https://api.staging.fusioncatalyst.io/)
Please note that breaking changes and bugs are to be expected, as the product is still under active development.
# App Management Commands
The `paw apps` commands allow you to create and manage applications within your Fusioncat projects.
## Commands
### apps list
List all applications in a project.
```bash
paw apps list --project-id
```
#### Options
* `--project-id` (required): The ID of the project
#### Examples
```bash
# List all apps in a project
paw apps list --project-id "project-uuid"
```
### apps new
Create a new application.
```bash
paw apps new --project-id --name [--description ]
```
#### Options
* `--project-id` (required): The ID of the project
* `--name` (required): Name of the application
* `--description`: Description of the application
#### Examples
```bash
# Create a simple app
paw apps new --project-id "project-uuid" --name "Web Frontend"
# Create an app with description
paw apps new --project-id "project-uuid" --name "Mobile App" --description "React Native mobile application"
```
## Understanding Applications
### What is an App?
In Fusioncat, an app represents a consumer or producer of your API definitions. Apps can be:
* Frontend applications (web, mobile)
* Backend services
* Microservices
* Third-party integrations
### App Configuration
Each app can:
* Generate code in different languages
* Have its own configuration
* Use specific schema versions
* Define custom mappings
### App Types
While the CLI doesn't enforce app types, common patterns include:
1. **Consumer Apps**: Use schemas to consume data
* Web frontends
* Mobile applications
* CLI tools
2. **Producer Apps**: Generate data conforming to schemas
* API servers
* Event producers
* Data pipelines
3. **Full-Stack Apps**: Both produce and consume
* Microservices
* API gateways
* Backend-for-frontend (BFF) services
## Code Generation
After creating an app, you can generate code for it:
```bash
# Generate TypeScript code
paw codegen app --app-id "app-uuid" --language typescript
# Generate Python code
paw codegen app --app-id "app-uuid" --language python
```
See [Code Generation](./codegen) for more details.
## Best Practices
### Naming Apps
* Use descriptive names that indicate the app's purpose
* Include the platform/technology if relevant
* Examples: "React Web App", "iOS Mobile App", "Order Processing Service"
### App Organization
1. **One app per deployable unit**: Each microservice, frontend, or mobile app should be separate
2. **Shared schemas**: Apps in the same project share schema definitions
3. **Version independence**: Each app can use different schema versions
### Development Workflow
1. Create project and schemas
2. Create app for your implementation
3. Generate initial code
4. Implement business logic
5. Regenerate when schemas change
## Examples
### Multi-App Project
```bash
# Create a project
paw projects new --name "E-commerce Platform" --belongs-to user
# Create schemas
paw schemas new --project-id "project-uuid" --name "Product" --type jsonschema --schema-file ./product.json
paw schemas new --project-id "project-uuid" --name "Order" --type jsonschema --schema-file ./order.json
# Create multiple apps
paw apps new --project-id "project-uuid" --name "Web Store" --description "Next.js web application"
paw apps new --project-id "project-uuid" --name "Mobile Store" --description "React Native app"
paw apps new --project-id "project-uuid" --name "Order Service" --description "Order processing microservice"
paw apps new --project-id "project-uuid" --name "Admin Dashboard" --description "Internal admin tool"
# Generate code for each app
paw codegen app --app-id "web-app-uuid" --language typescript
paw codegen app --app-id "mobile-app-uuid" --language typescript
paw codegen app --app-id "order-service-uuid" --language python
paw codegen app --app-id "admin-app-uuid" --language typescript
```
### Microservices Architecture
```bash
# Create apps for each microservice
paw apps new --project-id "project-uuid" --name "User Service" --description "User management"
paw apps new --project-id "project-uuid" --name "Product Service" --description "Product catalog"
paw apps new --project-id "project-uuid" --name "Cart Service" --description "Shopping cart"
paw apps new --project-id "project-uuid" --name "Payment Service" --description "Payment processing"
# Each service can generate code in its preferred language
paw codegen app --app-id "user-service-uuid" --language go
paw codegen app --app-id "product-service-uuid" --language java
paw codegen app --app-id "cart-service-uuid" --language python
paw codegen app --app-id "payment-service-uuid" --language typescript
```
## Related Commands
* [Projects](./projects) - Create projects to contain apps
* [Schemas](./schemas) - Define data structures for apps
* [Code Generation](./codegen) - Generate code for apps
* [Messages](./messages) - Create messages that apps can use
# Authentication
Source: https://docs.fusioncat.dev/cli-reference/authentication
Authenticate with the Fusioncat API
Fusioncat is currently in its alpha stage. The main API server is located at:
[https://api.staging.fusioncatalyst.io/](https://api.staging.fusioncatalyst.io/)
Please note that breaking changes and bugs are to be expected, as the product is still under active development.
# Authentication Commands
The `paw auth` commands allow you to authenticate with the Fusioncat API.
## Commands
### auth signin
Sign in to an existing Fusioncat account.
```bash
paw auth signin --email --password
# This call will return an authentication token that can be used for subsequent API calls.
# export FC_ACCESS_TOKEN="your-auth-token"
```
#### Options
* `--email` (required): Your email address
* `--password` (required): Your password
#### Examples
```bash
# Sign in without saving token (one-time use)
paw auth signin --email john@example.com --password mypassword
# This call will return an authentication token that can be used for subsequent API calls.
# export FC_ACCESS_TOKEN="your-auth-token"
```
### auth signup
Create a new Fusioncat account.
```bash
paw auth signup --email --password
# This call will return an authentication token that can be used for subsequent API calls.
# export FC_ACCESS_TOKEN="your-auth-token"
```
#### Options
* `--email` (required): Your email address
* `--password` (required): Your password (must be secure)
#### Examples
```bash
# Create new account and save token
paw auth signup --email newuser@example.com --password securepassword
export FC_ACCESS_TOKEN="your-auth-token"
```
### auth me
Get information about the current authenticated user.
```bash
paw auth me
```
This command requires a valid authentication token in the `FC_ACCESS_TOKEN` environment variable.
#### Examples
```bash
# Check current user
paw auth me
```
## Token Management
### Using Environment Variables
```bash
# View your current token
echo $FC_ACCESS_TOKEN
# Manually set a token
export FC_ACCESS_TOKEN="your-auth-token"
# Remove authentication
unset FC_ACCESS_TOKEN
```
### Token Security
* Tokens expire after a certain period (check with your administrator)
* Never commit tokens to version control
* Use environment-specific token management for CI/CD
## Troubleshooting
### Invalid Credentials
If you receive an authentication error:
1. Verify your email and password are correct
2. Check if your account is active
3. Ensure you're using the correct server URL
### Token Expired
If your token has expired:
```bash
# Sign in again to get a new token
paw auth signin --email your@email.com --password yourpassword --save-token
```
### No Token Found
If you see "authentication required" errors:
```bash
# Ensure you have a token set
echo $FC_ACCESS_TOKEN
# If empty, sign in again
paw auth signin --email your@email.com --password yourpassword --save-token
```
# Code Generation
Source: https://docs.fusioncat.dev/cli-reference/codegen
Generate code from your project definitions
Fusioncat is currently in its alpha stage. The main API server is located at:
[https://api.staging.fusioncatalyst.io/](https://api.staging.fusioncatalyst.io/)
Please note that breaking changes and bugs are to be expected, as the product is still under active development.
# Code Generation Commands
The `paw codegen` commands allow you to generate code in multiple programming languages from your FusionCatalyst project definitions.
## Commands
### codegen app
Generate code for a specific application.
```bash
paw codegen app --app-id [--language ]
```
#### Options
Currently only Golang codegeneration is properly implemented and tested.
* `--app-id` (required): The ID of the application to generate code for
* `--language`: Target programming language (overrides settings file)
* `typescript`
* `python`
* `java`
* `go`
#### Examples
```bash
# Generate using default language from settings
paw codegen app --app-id "app-uuid"
# Generate TypeScript code
paw codegen app --app-id "app-uuid" --language typescript
# Generate Python code
paw codegen app --app-id "app-uuid" --language python
```
## Supported Languages
### TypeScript
* **Use cases**: Node.js backends, React/Angular/Vue frontends
* **Features**: Full type safety, interfaces, async/await
* **Output**: TypeScript definitions and helper functions
### Python
* **Use cases**: Django/FastAPI backends, data processing
* **Features**: Type hints, dataclasses, async support
* **Output**: Python classes and type definitions
### Java
* **Use cases**: Spring Boot, enterprise applications
* **Features**: POJOs, builders, validation annotations
* **Output**: Java classes with getters/setters
### Go
* **Use cases**: Microservices, high-performance backends
* **Features**: Structs, interfaces, channels
* **Output**: Go structs and interfaces
## Generated Code Structure
### TypeScript Example
For a User schema:
```typescript
// Generated types
export interface User {
id: string;
email: string;
name: string;
createdAt: string;
}
// Generated validators
export function validateUser(data: unknown): User {
// Validation logic
}
// Generated API client
export class UserAPI {
async getUser(id: string): Promise {
// API call implementation
}
}
// Generated message handlers
export const userEvents = {
UserCreated: {
publish: async (event: UserCreatedEvent) => {
// Publish logic
},
subscribe: async (handler: (event: UserCreatedEvent) => Promise) => {
// Subscribe logic
}
}
};
```
### Python Example
```python
# Generated types
from dataclasses import dataclass
from typing import Optional
from datetime import datetime
@dataclass
class User:
id: str
email: str
name: str
created_at: datetime
# Generated validators
def validate_user(data: dict) -> User:
# Validation logic
pass
# Generated API client
class UserAPI:
async def get_user(self, id: str) -> User:
# API call implementation
pass
# Generated message handlers
class UserEvents:
@staticmethod
async def publish_user_created(event: UserCreatedEvent):
# Publish logic
pass
```
## Configuration
### Language Settings
Set default language in settings file:
```bash
paw init-settings-file --language typescript
```
Or in `fcsettings.json`:
```yaml
syntax_version: 1
server: https://api.fusioncat.dev
code_generation:
output_folder: generated
language: go
class_suffix: FCModel
```
### Output Directory
Generated code is placed in:
* `./fusioncant/` - Default output directory
```
generated/
├── c04beaff-870e-44ba-8dce-793715459e9f.go
```
## Code Generation Workflow
### 1. Initial Generation
```bash
# Create project and schemas
paw projects new --name "My API" --belongs-to user
paw schemas new --project-id "proj-id" --name "User" --type jsonschema --schema-file user.json
# Create app
paw apps new --project-id "proj-id" --name "Backend API"
# Generate initial code
paw codegen app --app-id "app-id" --language typescript
```
### 2. Development
1. Generated code provides the foundation
2. Add business logic on top
3. Don't modify generated files directly
### 3. Schema Updates
```bash
# Update schema
paw schemas update --schema-id "schema-id" --schema-file user-v2.json
# Regenerate code
paw codegen app --app-id "app-id"
# Generated code now includes new fields
```
## Integration Patterns
### Separate Generated Code
Keep generated code separate from business logic:
```typescript
// generated/types/user.ts (DO NOT EDIT)
export interface User {
id: string;
email: string;
name: string;
}
// src/services/user.service.ts (Your code)
import { User } from '../generated/types/user';
export class UserService {
async createUser(data: Omit): Promise {
// Your business logic
}
}
```
### Extend Generated Classes
```python
# generated/models/user.py (DO NOT EDIT)
@dataclass
class User:
id: str
email: str
name: str
# src/models/user_extended.py (Your code)
from generated.models.user import User
class ExtendedUser(User):
def get_display_name(self) -> str:
return f"{self.name} ({self.email})"
```
## Best Practices
### Version Control
1. **Commit generated code**: Include in version control
2. **Mark as generated**: Add headers indicating files are generated
3. **Regenerate in CI**: Ensure consistency
### Continuous Generation
```bash
# In your build script
#!/bin/bash
echo "Regenerating code..."
paw codegen app --app-id "$APP_ID"
echo "Running tests..."
npm test
echo "Building application..."
npm run build
```
### Multiple Apps
Generate different code for different apps:
```bash
# Frontend app - TypeScript
paw codegen app --app-id "frontend-id" --language typescript
# Backend app - Python
paw codegen app --app-id "backend-id" --language python
# Mobile app - TypeScript (React Native)
paw codegen app --app-id "mobile-id" --language typescript
```
## Examples
### Full Stack Application
```bash
# Create schemas
paw schemas new --project-id "proj" --name "User" --type jsonschema --schema-file schemas/user.json
paw schemas new --project-id "proj" --name "Product" --type jsonschema --schema-file schemas/product.json
# Create apps
paw apps new --project-id "proj" --name "React Frontend"
paw apps new --project-id "proj" --name "Node.js Backend"
# Generate TypeScript for both
paw codegen app --app-id "frontend-id" --language typescript
paw codegen app --app-id "backend-id" --language typescript
# Frontend uses generated types
# Backend uses generated types + API handlers
```
### Microservices
```bash
# Different languages for different services
paw codegen app --app-id "user-service" --language go
paw codegen app --app-id "order-service" --language java
paw codegen app --app-id "notification-service" --language python
paw codegen app --app-id "analytics-service" --language typescript
```
### Event-Driven System
```bash
# Generate event handlers
paw codegen app --app-id "event-producer" --language python
paw codegen app --app-id "event-consumer" --language typescript
# Generated code includes:
# - Event type definitions
# - Serialization/deserialization
# - Publisher/subscriber interfaces
# - Topic/queue configurations
```
## Troubleshooting
### Missing Dependencies
Generated code may require additional packages:
```bash
# TypeScript
npm install ajv uuid
# Python
pip install pydantic python-dateutil
# Java
# Add to pom.xml or build.gradle
# Go
go get github.com/go-playground/validator/v10
```
### Schema Compatibility
When updating schemas:
1. Consider backward compatibility
2. Use schema versioning
3. Update dependent apps gradually
### Code Conflicts
If regeneration causes conflicts:
1. Review schema changes
2. Check for breaking changes
3. Update business logic accordingly
## Related Commands
* [Apps](./apps) - Create applications to generate code for
* [Schemas](./schemas) - Define schemas for code generation
* [Projects](./projects) - Manage projects containing apps
# CLI Reference
Source: https://docs.fusioncat.dev/cli-reference/index
Complete reference for the Paw CLI
Fusioncat is currently in its alpha stage. The main API server is located at:
[https://api.staging.fusioncatalyst.io/](https://api.staging.fusioncatalyst.io/)
Please note that breaking changes and bugs are to be expected, as the product is still under active development.
# Paw CLI Reference
Paw is the official Fusioncat CLI that helps you manage projects, schemas, applications, and generate code across multiple programming languages.
## Installation
```bash
# Download the latest release
curl -L https://github.com/fusioncatltd/paw/releases/latest/download/paw_$(uname -s)_$(uname -m).tar.gz | tar xz
# Move to your PATH
sudo mv paw /usr/local/bin/
# Verify installation
paw --version
```
## Getting Started
1. **Initialize your settings file**
```bash
paw init-settings-file --server https://api.fusioncat.dev --language typescript
```
2. **Authenticate**
```bash
paw auth signin --email your@email.com --password yourpassword
```
3. **Create your first project**
```bash
paw projects new --name "My Project" --belongs-to user
```
## Global Options
* `--help, -h`: Show help
* `--version, -v`: Print the version
## Environment Variables
* `FC_ACCESS_TOKEN`: Authentication token for API access
* `FC_SERVER_URL`: Override the default server URL
* `FC_LANGUAGE`: Default language for code generation
## Configuration
Paw uses a settings file (`fcsettings.yaml`) to store project-specific configuration. This file is created when you run `paw init-settings-file`.
### Settings File Structure
```yaml
syntax_version: 1
server: https://api.fusioncat.dev
code_generation:
output_folder: generated
language: go
class_suffix: FCModel
```
## Next Steps
* [Authentication](./authentication) - Learn how to authenticate with the Fusioncat API
* [Project Management](./projects) - Create and manage projects
* [Schema Management](./schemas) - Work with schemas and versions
* [Code Generation](./codegen) - Generate code from your project definitions
# Settings Initialization
Source: https://docs.fusioncat.dev/cli-reference/init-settings
Initialize and configure your Paw CLI settings
Fusioncat is currently in its alpha stage. The main API server is located at:
[https://api.staging.fusioncatalyst.io/](https://api.staging.fusioncatalyst.io/)
Please note that breaking changes and bugs are to be expected, as the product is still under active development.
# Settings Initialization
The `paw init-settings-file` command creates a local configuration file for your FusionCatalyst project.
## Command
```bash
paw init-settings-file [options]
```
### Options
* `--server`: Server URL (default: [https://api.fusioncat.dev](https://api.fusioncat.dev))
* `--language`: Default code generation language
* `typescript`
* `python`
* `java`
* `go`
### Examples
```bash
# Basic initialization
paw init-settings-file
# Custom server and language
paw init-settings-file --server https://api.fusioncat.dev --language typescript
# Local development server
paw init-settings-file --server http://localhost:8080 --language go
```
## Settings File
The command creates a `fcsettings.yaml` file in your current directory:
```yaml
syntax_version: 1
server: https://api.fusioncat.dev
code_generation:
output_folder: generated
language: go
class_suffix: FCModel
```
### File Location
* **Created in**: Current working directory
* **File name**: `fcsettings.yaml`
* **Git**: Usually added to `.gitignore` for user-specific settings
## Configuration Options
### server
The FusionCatalyst API server URL:
* **Production**: `https://api.fusioncat.dev`
* **Staging**: `https://staging-api.fusioncat.dev`
* **Local**: `http://localhost:8080`
### language
Default language for code generation:
* `typescript` - For Node.js, React, Angular, Vue
* `python` - For Django, FastAPI, Flask
* `java` - For Spring Boot, Micronaut
* `go` - For Go backend applications
## Workflows
### New Project Setup
```bash
# 1. Initialize settings
paw init-settings-file --language typescript
# 2. Authenticate
paw auth signin --email you@example.com --password yourpass
# 3. Create project
paw projects new --name "My API"
```
### Team Collaboration
For team projects, each member:
```bash
# 1. Clone repository
git clone https://github.com/team/project
# 2. Initialize their own settings
cd project
paw init-settings-file
# 3. Authenticate with their credentials
paw auth signin --email member@team.com --password theirpass
```
## Environment Variables
Settings can be overridden with environment variables:
```bash
# Override server URL
export FC_SERVER_URL="https://custom.fusioncat.dev"
# Override default language
export FC_LANGUAGE="python"
# Set authentication token
export FC_ACCESS_TOKEN="your-auth-token"
```
Priority order:
1. Command line flags
2. Environment variables
3. Settings file
4. Default values
## Multiple Projects
Managing multiple projects in different directories:
```bash
# Project A
cd ~/projects/api-a
paw init-settings-file
# Project B
cd ~/projects/api-b
paw init-settings-file
# Each directory has its own settings
```
## Best Practices
### Git Configuration
Add to `.gitignore`:
```gitignore
# Fusioncat settings
fcsettings.yaml
# But track a template
fcsettings.yaml.example
```
Create `fcsettings.yaml.example`:
```yaml
syntax_version: 1
server: https://api.fusioncat.dev
code_generation:
output_folder: generated
language: go
class_suffix: FCModel
```
### Security
1. **Never commit**: Authentication tokens or sensitive data
2. **Use environment**: For CI/CD authentication
3. **Personal settings**: Each developer has their own file
### Team Setup
Document in your README:
````markdown
## Setup
1. Initialize your settings:
```bash
paw init-settings-file --language typescript
````
2. Authenticate:
```bash
paw auth signin --email your@email.com --password yourpass --save-token
```
3. Generate code:
```bash
paw codegen app --app-id "app-uuid"
```
````
## Troubleshooting
### Settings Not Found
```bash
Error: No settings file found
````
Solution:
```bash
# Create settings file
paw init-settings-file
```
### Server Connection
```bash
Error: Cannot connect to server
```
Solution:
```bash
# Check server URL
cat fcsettings.yaml
# Update if needed
paw init-settings-file --server https://api.fusioncat.dev
```
## Related Commands
* [Authentication](./authentication) - Sign in after initializing
* [Projects](./projects) - Create or connect to projects
* [Code Generation](./codegen) - Use the configured language
# Message Management
Source: https://docs.fusioncat.dev/cli-reference/messages
Create and manage messages based on schemas
Fusioncat is currently in its alpha stage. The main API server is located at:
[https://api.staging.fusioncatalyst.io/](https://api.staging.fusioncatalyst.io/)
Please note that breaking changes and bugs are to be expected, as the product is still under active development.
# Message Management Commands
The `paw messages` commands allow you to create and manage messages that are based on your schema definitions.
## Commands
### messages list
List all messages in a project.
```bash
paw messages list --project-id
```
#### Options
* `--project-id` (required): The ID of the project
#### Examples
```bash
# List all messages
paw messages list --project-id "project-uuid"
```
### messages new
Create a new message based on a schema.
```bash
paw messages new --project-id --name --schema-id --schema-version [--description ]
```
#### Options
* `--project-id` (required): The ID of the project
* `--name` (required): Name of the message
* `--schema-id` (required): The ID of the schema this message is based on
* `--schema-version` (required): The version of the schema to use
* `--description`: Description of the message
#### Examples
```bash
# Create a message
paw messages new --project-id "project-uuid" --name "UserCreatedEvent" --schema-id "user-schema-uuid" --schema-version "v1.0.0"
# Create with description
paw messages new --project-id "project-uuid" --name "OrderShippedNotification" --schema-id "order-schema-uuid" --schema-version "v2.1.0" --description "Sent when order ships"
```
## Understanding Messages
### What is a Message?
A message is a concrete implementation of a schema used for:
* Event definitions in event-driven architectures
* API request/response definitions
* Data transfer objects (DTOs)
* Queue message formats
### Message vs Schema
* **Schema**: The abstract data structure definition
* **Message**: A specific use case of that schema
Example:
* Schema: `User` (defines user data structure)
* Messages: `UserCreatedEvent`, `UserUpdatedEvent`, `UserProfileResponse`
### Message Versioning
Messages are tied to specific schema versions:
* When a schema updates, existing messages continue using their version
* Create new messages for new schema versions
* Allows gradual migration
## Event-Driven Architecture
Messages are particularly useful for event-driven systems:
```bash
# Create event schemas
paw schemas new --project-id "project-uuid" --name "OrderEvent" --type jsonschema --schema-file ./order-event.json
# Create specific event messages
paw messages new --project-id "project-uuid" --name "OrderCreated" --schema-id "order-event-uuid" --schema-version "v1.0.0"
paw messages new --project-id "project-uuid" --name "OrderShipped" --schema-id "order-event-uuid" --schema-version "v1.0.0"
paw messages new --project-id "project-uuid" --name "OrderDelivered" --schema-id "order-event-uuid" --schema-version "v1.0.0"
paw messages new --project-id "project-uuid" --name "OrderCancelled" --schema-id "order-event-uuid" --schema-version "v1.0.0"
```
## Best Practices
### Naming Conventions
1. **Events**: Use past tense - `UserCreated`, `OrderShipped`
2. **Commands**: Use imperative - `CreateUser`, `ShipOrder`
3. **Requests/Responses**: Be descriptive - `GetUserRequest`, `UserProfileResponse`
### Message Organization
Group related messages:
```
User Domain:
- UserCreatedEvent
- UserUpdatedEvent
- UserDeletedEvent
- GetUserRequest
- UserResponse
Order Domain:
- OrderPlacedEvent
- OrderShippedEvent
- OrderDeliveredEvent
- CreateOrderCommand
- OrderStatusResponse
```
### Schema Reuse
Multiple messages can use the same schema:
```bash
# One schema, multiple messages
paw messages new --project-id "pid" --name "CreateUserRequest" --schema-id "user-schema" --schema-version "v1"
paw messages new --project-id "pid" --name "UpdateUserRequest" --schema-id "user-schema" --schema-version "v1"
paw messages new --project-id "pid" --name "UserResponse" --schema-id "user-schema" --schema-version "v1"
```
## Examples
### API Message Definitions
```bash
# Request/Response pairs
paw messages new --project-id "project-uuid" \
--name "CreateProductRequest" \
--schema-id "product-schema-uuid" \
--schema-version "v1.0.0" \
--description "API request to create a new product"
paw messages new --project-id "project-uuid" \
--name "ProductResponse" \
--schema-id "product-schema-uuid" \
--schema-version "v1.0.0" \
--description "API response containing product data"
paw messages new --project-id "project-uuid" \
--name "ProductListResponse" \
--schema-id "product-list-schema-uuid" \
--schema-version "v1.0.0" \
--description "API response for product listings"
```
### Event Sourcing
```bash
# Define events for an aggregate
paw messages new --project-id "project-uuid" --name "AccountOpened" --schema-id "account-event-uuid" --schema-version "v1"
paw messages new --project-id "project-uuid" --name "MoneyDeposited" --schema-id "transaction-event-uuid" --schema-version "v1"
paw messages new --project-id "project-uuid" --name "MoneyWithdrawn" --schema-id "transaction-event-uuid" --schema-version "v1"
paw messages new --project-id "project-uuid" --name "AccountClosed" --schema-id "account-event-uuid" --schema-version "v1"
```
### Microservices Communication
```bash
# Service A publishes
paw messages new --project-id "project-uuid" \
--name "InventoryUpdatedEvent" \
--schema-id "inventory-schema-uuid" \
--schema-version "v2.0.0"
# Service B consumes and publishes
paw messages new --project-id "project-uuid" \
--name "PriceRecalculationCommand" \
--schema-id "pricing-command-uuid" \
--schema-version "v1.0.0"
# Service C responds
paw messages new --project-id "project-uuid" \
--name "PriceUpdatedEvent" \
--schema-id "price-event-uuid" \
--schema-version "v1.0.0"
```
## Working with Servers and Resources
Messages are often used with servers and resources:
```bash
# Create a Kafka server
paw servers new --project-id "project-uuid" --name "Event Bus" --type "async+kafka" --description "Main event bus"
# Create topics for messages
paw resources new --server-id "server-uuid" --name "user-events" --type topic --mode write
paw resources new --server-id "server-uuid" --name "order-events" --type topic --mode readwrite
# Messages can now be published to these topics
```
## Related Commands
* [Schemas](./schemas) - Define data structures for messages
* [Servers](./servers) - Create servers for message transport
* [Resources](./resources) - Define topics/queues for messages
* [Code Generation](./codegen) - Generate message handling code
# Project Management
Source: https://docs.fusioncat.dev/cli-reference/projects
Create and manage Fusioncat projects
Fusioncat is currently in its alpha stage. The main API server is located at:
[https://api.staging.fusioncatalyst.io/](https://api.staging.fusioncatalyst.io/)
Please note that breaking changes and bugs are to be expected, as the product is still under active development.
# Project Management Commands
The `paw projects` commands allow you to create, list, and manage Fusioncat projects.
## Commands
### projects list
List all projects accessible to you.
```bash
paw projects list
```
#### Examples
```bash
# List all projects
paw projects list
```
### projects new
Create a new project.
```bash
paw projects new --name --belongs-to [options]
```
#### Options
* `--name` (required): Project name
* `--belongs-to` (required): Whether the project belongs to `user` or `workspace`
* `--workspace-id`: If project belongs to a workspace, specify the workspace ID
* `--private`: Make the project private (default: false)
* `--description`: Project description
#### Examples
```bash
# Create a user project
paw projects new --name "My API Project" --belongs-to user --description "Main API definitions"
# Create a private user project
paw projects new --name "Internal Tools" --belongs-to user --private
# Create a workspace project
paw projects new --name "Team Project" --belongs-to workspace --workspace-id "workspace-uuid"
```
### projects import
Import a project from a definition file.
```bash
paw projects import --file --project-id
```
#### Options
* `--file` (required): Path to the project definition file
* `--project-id` (required): The ID of the project to import into
#### Examples
```bash
# Import project definition
paw projects import --file ./project-export.json --project-id "project-uuid"
```
### projects generate
Generate code for a project (legacy command - use `codegen app` instead).
```bash
paw projects generate --app-id --project-id
```
#### Options
* `--app-id` (required): The ID of the application
* `--project-id` (required): The ID of the project
## Working with Projects
### Project Structure
A Fusioncat project contains:
* **Apps**: Applications that use your schemas
* **Schemas**: Data structure definitions with versioning
* **Messages**: Messages based on schemas
* **Servers**: Event-driven server configurations
* **Resources**: Server resources (topics, queues, endpoints)
### Project Settings
After creating a project, you can connect it to your local settings file:
```bash
# Initialize settings with project ID
paw init-settings-file --working-with-project "project-uuid"
```
This creates a `.paw-settings.json` file that links your local directory to the project.
### Project Ownership
Projects can belong to:
* **User**: Personal projects owned by your account
* **Workspace**: Shared projects owned by a workspace
## Best Practices
### Naming Conventions
* Use descriptive names for projects
* Include the purpose in the project name
* For workspace projects, consider prefixing with team/department
### Organization
1. **One project per domain**: Keep related schemas and apps together
2. **Use workspaces for teams**: Share projects across team members
3. **Private vs Public**: Make internal projects private
### Project Lifecycle
1. **Create**: Start with a clear project structure
2. **Define**: Add schemas and messages
3. **Implement**: Create apps and generate code
4. **Version**: Use schema versioning for changes
5. **Export/Import**: Backup and share project definitions
## Examples
### Complete Project Setup
```bash
# 1. Create a new project
paw projects new --name "E-commerce API" --belongs-to user
# 2. List projects to get the ID
paw projects list
# 3. Initialize local settings
paw init-settings-file --working-with-project "project-uuid"
# 4. Create a schema
paw schemas new --project-id "project-uuid" --name "Product" --type jsonschema --schema-file ./schemas/product.json
# 5. Create an app
paw apps new --project-id "project-uuid" --name "Frontend App" --description "React frontend"
# 6. Generate code
paw codegen app --app-id "app-uuid" --language typescript
```
## Related Commands
* [Workspaces](./workspaces) - Manage workspaces for team collaboration
* [Apps](./apps) - Create applications within projects
* [Schemas](./schemas) - Define data structures
* [Code Generation](./codegen) - Generate code from projects
# Resource Management
Source: https://docs.fusioncat.dev/cli-reference/resources
Create and manage server resources like topics, queues, and endpoints
Fusioncat is currently in its alpha stage. The main API server is located at:
[https://api.staging.fusioncatalyst.io/](https://api.staging.fusioncatalyst.io/)
Please note that breaking changes and bugs are to be expected, as the product is still under active development.
# Resource Management Commands
The `paw resources` commands allow you to create and manage resources within servers, such as topics, queues, exchanges, and endpoints.
## Commands
### resources list
List all resources in a server.
```bash
paw resources list --server-id
```
#### Options
* `--server-id` (required): The ID of the server
#### Examples
```bash
# List all resources
paw resources list --server-id "server-uuid"
```
### resources new
Create a new resource.
```bash
paw resources new --server-id --name --type --mode [--description ]
```
#### Options
* `--server-id` (required): The ID of the server
* `--name` (required): Name of the resource
* `--type` (required): Type of the resource
* `topic`: Kafka topic or similar
* `exchange`: AMQP exchange
* `queue`: Message queue
* `table`: Data table
* `endpoint`: HTTP endpoint
* `--mode` (required): Access mode for the resource
* `read`: Read-only access
* `write`: Write-only access
* `readwrite`: Full read/write access
* `bind`: Binding mode (for AMQP)
* `--description`: Description of the resource
#### Examples
```bash
# Create a Kafka topic
paw resources new --server-id "kafka-server-uuid" --name "user-events" --type topic --mode readwrite
# Create an AMQP exchange
paw resources new --server-id "amqp-server-uuid" --name "order-exchange" --type exchange --mode write
# Create a queue
paw resources new --server-id "amqp-server-uuid" --name "order-processing" --type queue --mode read
# Create a webhook endpoint
paw resources new --server-id "webhook-server-uuid" --name "payment-callback" --type endpoint --mode write
```
## Resource Types by Server
### Kafka Server Resources
**Topics** - Event streams:
```bash
# Create topics for different event types
paw resources new --server-id "kafka-uuid" --name "user.events" --type topic --mode readwrite
paw resources new --server-id "kafka-uuid" --name "order.events" --type topic --mode write
paw resources new --server-id "kafka-uuid" --name "inventory.events" --type topic --mode read
```
### AMQP Server Resources
**Exchanges** - Message routing:
```bash
# Direct exchange
paw resources new --server-id "amqp-uuid" --name "direct-exchange" --type exchange --mode write
# Topic exchange
paw resources new --server-id "amqp-uuid" --name "events.topic" --type exchange --mode write
# Fanout exchange
paw resources new --server-id "amqp-uuid" --name "broadcast.fanout" --type exchange --mode write
```
**Queues** - Message storage:
```bash
# Work queues
paw resources new --server-id "amqp-uuid" --name "email-queue" --type queue --mode readwrite
paw resources new --server-id "amqp-uuid" --name "sms-queue" --type queue --mode read
# Dead letter queue
paw resources new --server-id "amqp-uuid" --name "failed-messages-dlq" --type queue --mode readwrite
```
### Webhook Server Resources
**Endpoints** - HTTP callbacks:
```bash
# Incoming webhooks
paw resources new --server-id "webhook-uuid" --name "github-webhook" --type endpoint --mode read
# Outgoing webhooks
paw resources new --server-id "webhook-uuid" --name "slack-notification" --type endpoint --mode write
```
## Access Modes
### read
* Can consume/receive from the resource
* For queues: dequeue messages
* For topics: subscribe and consume
* For endpoints: receive webhooks
### write
* Can produce/send to the resource
* For queues: enqueue messages
* For topics: publish events
* For endpoints: send webhooks
### readwrite
* Full access to both read and write
* Most common for internal services
### bind
* Special mode for AMQP
* Bind queues to exchanges
* Set up routing rules
## Best Practices
### Naming Conventions
1. **Topics**: Use dot notation - `domain.entity.action`
```bash
paw resources new --server-id "id" --name "user.profile.updated" --type topic --mode write
paw resources new --server-id "id" --name "order.payment.completed" --type topic --mode write
```
2. **Queues**: Use descriptive names with purpose
```bash
paw resources new --server-id "id" --name "email-notification-queue" --type queue --mode read
paw resources new --server-id "id" --name "report-generation-queue" --type queue --mode readwrite
```
3. **Endpoints**: Include action and target
```bash
paw resources new --server-id "id" --name "stripe-payment-webhook" --type endpoint --mode read
paw resources new --server-id "id" --name "customer-notification-endpoint" --type endpoint --mode write
```
### Resource Organization
Group related resources:
```bash
# User domain resources
paw resources new --server-id "kafka" --name "user.created" --type topic --mode write
paw resources new --server-id "kafka" --name "user.updated" --type topic --mode write
paw resources new --server-id "kafka" --name "user.deleted" --type topic --mode write
# Order processing resources
paw resources new --server-id "amqp" --name "order-validation-queue" --type queue --mode readwrite
paw resources new --server-id "amqp" --name "order-fulfillment-queue" --type queue --mode readwrite
paw resources new --server-id "amqp" --name "order-notification-queue" --type queue --mode write
```
### Access Control
Principle of least privilege:
```bash
# Producer service - write only
paw resources new --server-id "id" --name "events" --type topic --mode write
# Consumer service - read only
paw resources new --server-id "id" --name "events" --type topic --mode read
# Processing service - full access
paw resources new --server-id "id" --name "work-queue" --type queue --mode readwrite
```
## Examples
### Event-Driven Microservices
```bash
# Create Kafka server
paw servers new --project-id "proj" --name "Event Bus" --type "async+kafka" --description "Main event bus"
# User service resources
paw resources new --server-id "kafka" --name "user.events" --type topic --mode write --description "User service publishes"
# Order service resources
paw resources new --server-id "kafka" --name "user.events" --type topic --mode read --description "Order service subscribes"
paw resources new --server-id "kafka" --name "order.events" --type topic --mode write --description "Order service publishes"
# Notification service resources
paw resources new --server-id "kafka" --name "order.events" --type topic --mode read --description "Notification service subscribes"
```
### Task Queue System
```bash
# Create AMQP server
paw servers new --project-id "proj" --name "Task Queue" --type "async+amqp" --description "Background jobs"
# Create exchange
paw resources new --server-id "amqp" --name "tasks.direct" --type exchange --mode write
# Create queues
paw resources new --server-id "amqp" --name "email-tasks" --type queue --mode readwrite
paw resources new --server-id "amqp" --name "report-tasks" --type queue --mode readwrite
paw resources new --server-id "amqp" --name "cleanup-tasks" --type queue --mode readwrite
# Dead letter queue
paw resources new --server-id "amqp" --name "failed-tasks-dlq" --type queue --mode readwrite
```
### Webhook Integration
```bash
# Create webhook server
paw servers new --project-id "proj" --name "Webhooks" --type "async+webhook" --description "External integrations"
# Incoming webhooks
paw resources new --server-id "webhook" --name "stripe-payment" --type endpoint --mode read
paw resources new --server-id "webhook" --name "github-push" --type endpoint --mode read
# Outgoing webhooks
paw resources new --server-id "webhook" --name "slack-alert" --type endpoint --mode write
paw resources new --server-id "webhook" --name "customer-notification" --type endpoint --mode write
```
## Generated Code
Resources generate connection code:
```typescript
// Generated Kafka consumer
export const userEventsConsumer = {
topic: 'user.events',
mode: 'read',
subscribe: async (handler: (event: UserEvent) => Promise) => {
// Generated subscription code
}
};
// Generated AMQP producer
export const taskQueueProducer = {
queue: 'email-tasks',
mode: 'write',
send: async (task: EmailTask) => {
// Generated send code
}
};
```
## Related Commands
* [Servers](./servers) - Create servers to contain resources
* [Messages](./messages) - Define messages to send through resources
* [Code Generation](./codegen) - Generate resource handling code
# Schema Management
Source: https://docs.fusioncat.dev/cli-reference/schemas
Create and manage schemas with versioning support
Fusioncat is currently in its alpha stage. The main API server is located at:
[https://api.staging.fusioncatalyst.io/](https://api.staging.fusioncatalyst.io/)
Please note that breaking changes and bugs are to be expected, as the product is still under active development.
# Schema Management Commands
The `paw schemas` commands allow you to create, update, and manage schemas with full versioning support.
## Commands
### schemas list
List all schemas in a project.
```bash
paw schemas list --project-id
```
#### Options
* `--project-id` (required): The ID of the project
#### Examples
```bash
# List all schemas
paw schemas list --project-id "project-uuid"
```
### schemas new
Create a new schema.
```bash
paw schemas new --project-id --name --type --schema-file [--description ]
```
#### Options
* `--project-id` (required): The ID of the project
* `--name` (required): Name of the schema
* `--type` (required): Type of the schema (e.g., `jsonschema`)
* `--schema-file` (required): Path to the schema definition file
* `--description`: Description of the schema
#### Examples
```bash
# Create a JSON Schema
paw schemas new --project-id "project-uuid" --name "User" --type jsonschema --schema-file ./schemas/user.json
# Create with description
paw schemas new --project-id "project-uuid" --name "Product" --type jsonschema --schema-file ./product.json --description "Product catalog schema"
```
### schemas update
Update an existing schema (creates a new version).
```bash
paw schemas update --schema-id --schema-file
```
#### Options
* `--schema-id` (required): The ID of the schema to update
* `--schema-file` (required): Path to the updated schema definition
#### Examples
```bash
# Update a schema
paw schemas update --schema-id "schema-uuid" --schema-file ./schemas/user-v2.json
```
### schemas versions
List all versions of a schema.
```bash
paw schemas versions --schema-id
```
#### Options
* `--schema-id` (required): The ID of the schema
#### Examples
```bash
# List schema versions
paw schemas versions --schema-id "schema-uuid"
```
### schemas get-version
Get a specific version of a schema.
```bash
paw schemas get-version --schema-id --version-id
```
#### Options
* `--schema-id` (required): The ID of the schema
* `--version-id` (required): The version ID of the schema
#### Examples
```bash
# Get specific version
paw schemas get-version --schema-id "schema-uuid" --version-id "v1.0.0"
```
## Schema Types
### JSON Schema
The most common schema type. Define your data structures using JSON Schema specification.
Example `user.json`:
```json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"title": "User",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"name": {
"type": "string",
"minLength": 1
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": ["id", "email", "name"]
}
```
## Schema Versioning
### How Versioning Works
1. **Immutable Versions**: Each schema version is immutable once created
2. **Automatic Versioning**: Updates create new versions automatically
3. **Version History**: Full history is maintained for auditing
4. **App Independence**: Different apps can use different versions
### Version Management
```bash
# Create initial schema (v1)
paw schemas new --project-id "project-uuid" --name "Order" --type jsonschema --schema-file ./order-v1.json
# List schemas to get ID
paw schemas list --project-id "project-uuid"
# Update schema (creates v2)
paw schemas update --schema-id "schema-uuid" --schema-file ./order-v2.json
# View all versions
paw schemas versions --schema-id "schema-uuid"
# Get specific version
paw schemas get-version --schema-id "schema-uuid" --version-id "version-uuid"
```
## Best Practices
### Schema Design
1. **Start Simple**: Begin with core fields, add complexity gradually
2. **Use Standard Formats**: Leverage format validators (email, uuid, date-time)
3. **Document Fields**: Use descriptions in your schemas
4. **Required Fields**: Only mark truly required fields as required
### Versioning Strategy
1. **Backward Compatibility**: Try to maintain compatibility when possible
2. **Semantic Versioning**: Use clear version numbering
3. **Migration Path**: Document changes between versions
4. **Deprecation**: Mark old fields as deprecated before removal
### Schema Organization
```
schemas/
├── v1/
│ ├── user.json
│ ├── product.json
│ └── order.json
├── v2/
│ ├── user.json # Added 'role' field
│ ├── product.json # No changes
│ └── order.json # Added 'status' enum
└── README.md # Document changes
```
## Examples
### Evolution of a Schema
```bash
# Version 1: Basic user schema
cat > user-v1.json << 'EOF'
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"id": {"type": "string"},
"name": {"type": "string"}
}
}
EOF
paw schemas new --project-id "project-uuid" --name "User" --type jsonschema --schema-file user-v1.json
# Version 2: Add email field
cat > user-v2.json << 'EOF'
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"id": {"type": "string"},
"name": {"type": "string"},
"email": {"type": "string", "format": "email"}
}
}
EOF
paw schemas update --schema-id "schema-uuid" --schema-file user-v2.json
# Version 3: Add required fields and validation
cat > user-v3.json << 'EOF'
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"id": {"type": "string", "format": "uuid"},
"name": {"type": "string", "minLength": 1},
"email": {"type": "string", "format": "email"}
},
"required": ["id", "email"]
}
EOF
paw schemas update --schema-id "schema-uuid" --schema-file user-v3.json
```
### Complex Schema Example
```json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"title": "Order",
"properties": {
"orderId": {
"type": "string",
"format": "uuid"
},
"customer": {
"$ref": "#/definitions/customer"
},
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/orderItem"
}
},
"status": {
"type": "string",
"enum": ["pending", "processing", "shipped", "delivered", "cancelled"]
},
"total": {
"type": "number",
"minimum": 0
}
},
"definitions": {
"customer": {
"type": "object",
"properties": {
"customerId": {"type": "string"},
"name": {"type": "string"},
"email": {"type": "string", "format": "email"}
}
},
"orderItem": {
"type": "object",
"properties": {
"productId": {"type": "string"},
"quantity": {"type": "integer", "minimum": 1},
"price": {"type": "number", "minimum": 0}
}
}
}
}
```
## Related Commands
* [Messages](./messages) - Create messages based on schemas
* [Code Generation](./codegen) - Generate code from schemas
* [Projects](./projects) - Manage projects containing schemas
# Server Management
Source: https://docs.fusioncat.dev/cli-reference/servers
Create and manage event-driven servers
Fusioncat is currently in its alpha stage. The main API server is located at:
[https://api.staging.fusioncatalyst.io/](https://api.staging.fusioncatalyst.io/)
Please note that breaking changes and bugs are to be expected, as the product is still under active development.
# Server Management Commands
The `paw servers` commands allow you to create and manage servers for event-driven architectures.
## Commands
### servers list
List all servers in a project.
```bash
paw servers list --project-id
```
#### Options
* `--project-id` (required): The ID of the project
#### Examples
```bash
# List all servers
paw servers list --project-id "project-uuid"
```
### servers new
Create a new server.
```bash
paw servers new --project-id --name --type --description
```
#### Options
* `--project-id` (required): The ID of the project
* `--name` (required): Name of the server
* `--type` (required): Type of the server
* `async+kafka`: Apache Kafka server
* `async+amqp`: AMQP server (RabbitMQ, etc.)
* `async+webhook`: Webhook-based server
* `--description` (required): Description of the server
#### Examples
```bash
# Create a Kafka server
paw servers new --project-id "project-uuid" --name "Event Stream" --type "async+kafka" --description "Main event streaming platform"
# Create an AMQP server
paw servers new --project-id "project-uuid" --name "Message Queue" --type "async+amqp" --description "RabbitMQ message broker"
# Create a webhook server
paw servers new --project-id "project-uuid" --name "Webhook Gateway" --type "async+webhook" --description "External webhook integrations"
```
## Server Types
### async+kafka
Apache Kafka servers for high-throughput event streaming:
* **Use cases**: Event sourcing, log aggregation, real-time analytics
* **Resources**: Topics with read/write modes
* **Best for**: High volume, ordered events
### async+amqp
AMQP servers (RabbitMQ, Azure Service Bus, etc.):
* **Use cases**: Task queues, RPC, pub/sub messaging
* **Resources**: Exchanges, queues with various routing
* **Best for**: Reliable delivery, complex routing
### async+webhook
Webhook-based servers for HTTP callbacks:
* **Use cases**: Third-party integrations, notifications
* **Resources**: Endpoints for sending/receiving webhooks
* **Best for**: External system integration
## Working with Servers
### Server Architecture
Servers act as the transport layer for your messages:
```
Project
├── Schemas (data structures)
├── Messages (concrete implementations)
├── Servers (transport layer)
│ ├── Kafka Server
│ ├── AMQP Server
│ └── Webhook Server
└── Resources (topics, queues, endpoints)
```
### Server Resources
After creating a server, add resources to it:
```bash
# Create Kafka server
paw servers new --project-id "project-uuid" --name "Events" --type "async+kafka" --description "Event bus"
# Add topics
paw resources new --server-id "server-uuid" --name "user-events" --type topic --mode readwrite
paw resources new --server-id "server-uuid" --name "order-events" --type topic --mode write
```
## Best Practices
### Server Organization
1. **Separate by Purpose**: Different servers for different use cases
2. **Environment Parity**: Same server types across environments
3. **Clear Naming**: Include purpose in server name
### Multi-Server Architecture
```bash
# Event streaming for real-time data
paw servers new --project-id "pid" --name "Stream Processing" --type "async+kafka" --description "Real-time event stream"
# Task queue for background jobs
paw servers new --project-id "pid" --name "Job Queue" --type "async+amqp" --description "Background job processing"
# External integrations
paw servers new --project-id "pid" --name "Partner Webhooks" --type "async+webhook" --description "Partner system callbacks"
```
### Server Selection Guide
Choose based on your requirements:
| Requirement | Recommended Server |
| ------------------ | ------------------------- |
| High throughput | async+kafka |
| Ordered events | async+kafka |
| Complex routing | async+amqp |
| Dead letter queues | async+amqp |
| External systems | async+webhook |
| Simple pub/sub | async+amqp or async+kafka |
## Examples
### E-commerce Event Architecture
```bash
# Create main event bus
paw servers new --project-id "ecommerce-uuid" \
--name "Event Bus" \
--type "async+kafka" \
--description "Main event streaming platform"
# Create task queue
paw servers new --project-id "ecommerce-uuid" \
--name "Task Queue" \
--type "async+amqp" \
--description "Background job processing"
# Create webhook server
paw servers new --project-id "ecommerce-uuid" \
--name "Payment Webhooks" \
--type "async+webhook" \
--description "Payment provider callbacks"
```
### Services Communication
```bash
# Inter-service communication
paw servers new --project-id "microservices-uuid" \
--name "Service Bus" \
--type "async+amqp" \
--description "Inter-service message bus"
# Event store
paw servers new --project-id "microservices-uuid" \
--name "Event Store" \
--type "async+kafka" \
--description "Event sourcing store"
# External APIs
paw servers new --project-id "microservices-uuid" \
--name "API Gateway Webhooks" \
--type "async+webhook" \
--description "External API callbacks"
```
### IoT Data Pipeline
```bash
# Device data ingestion
paw servers new --project-id "iot-uuid" \
--name "Device Stream" \
--type "async+kafka" \
--description "IoT device data stream"
# Command and control
paw servers new --project-id "iot-uuid" \
--name "Device Commands" \
--type "async+amqp" \
--description "Device command queue"
```
## Server Configuration
While the CLI creates server definitions, actual connection details and configuration are managed through:
1. Environment-specific configuration files
2. Generated code configuration
3. Runtime environment variables
Example generated code structure:
```typescript
// Generated configuration
export const servers = {
eventBus: {
type: 'kafka',
name: 'Event Bus',
// Connection details from environment
brokers: process.env.KAFKA_BROKERS?.split(',') || ['localhost:9092'],
},
taskQueue: {
type: 'amqp',
name: 'Task Queue',
// Connection details from environment
url: process.env.AMQP_URL || 'amqp://localhost',
}
};
```
## Related Commands
* [Resources](./resources) - Create topics, queues, and endpoints
* [Messages](./messages) - Define messages to send through servers
* [Code Generation](./codegen) - Generate server connection code
# Workspace Management
Source: https://docs.fusioncat.dev/cli-reference/workspaces
Create and manage workspaces for team collaboration
Fusioncat is currently in its alpha stage. The main API server is located at:
[https://api.staging.fusioncatalyst.io/](https://api.staging.fusioncatalyst.io/)
Please note that breaking changes and bugs are to be expected, as the product is still under active development.
# Workspace Management Commands
The `paw workspaces` commands allow you to create and manage workspaces for team collaboration.
## Commands
### workspaces list
List all workspaces you have access to.
```bash
paw workspaces list
```
#### Examples
```bash
# List all workspaces
paw workspaces list
```
### workspaces new
Create a new workspace.
```bash
paw workspaces new --name [--description ]
```
#### Options
* `--name` (required): Workspace name
* `--description`: Optional description of the workspace
#### Examples
```bash
# Create a workspace
paw workspaces new --name "Engineering Team" --description "Workspace for the engineering team"
# Create a minimal workspace
paw workspaces new --name "QA Team"
```
## Working with Workspaces
### What are Workspaces?
Workspaces are collaborative environments where teams can:
* Share projects
* Manage access permissions
* Organize resources by team or department
* Collaborate on API definitions
### Workspace Projects
After creating a workspace, you can create projects that belong to it:
```bash
# Create a workspace
paw workspaces new --name "API Team"
# List workspaces to get the ID
paw workspaces list
# Create a project in the workspace
paw projects new --name "Shared APIs" --belongs-to workspace --workspace-id "workspace-uuid"
```
### Workspace Members
Workspace membership and permissions are managed through the FusionCatalyst web interface or API. The CLI focuses on workspace and project creation.
## Best Practices
### Workspace Organization
1. **One workspace per team**: Keep team resources together
2. **Clear naming**: Use descriptive names that identify the team or purpose
3. **Documentation**: Use descriptions to clarify workspace purpose
### Workspace Structure Example
```
FintechEngineeringTeamWorkspace/
├── PaymentProject
├── AccountingProject
└── NotificationsProject
ComplianceEngineeringTeamWorkspace/
├── LegalClaimsProject
└── AntiMoneyLaunderingProject
```
### Access Control
* Workspace owners can manage members
* Members can create and modify projects
* Project-level permissions override workspace permissions
## Examples
### Complete Team Setup
```bash
# 1. Create a workspace for your team
paw workspaces new --name "Backend Team" --description "Backend engineering workspace"
# 2. List workspaces to get the ID
paw workspaces list
# 3. Create a shared project
paw projects new --name "Microservices APIs" --belongs-to workspace --workspace-id "workspace-uuid"
# 4. Team members can now collaborate on the project
paw apps new --project-id "project-uuid" --name "User Service" --description "User management service"
```
### Migration from User to Workspace
If you have personal projects that should be shared:
1. Export the project definition
2. Create a new workspace
3. Create a new project in the workspace
4. Import the project definition
```bash
# Export existing project (through web interface or API)
# Create workspace
paw workspaces new --name "Team Workspace"
# Create new project in workspace
paw projects new --name "Migrated Project" --belongs-to workspace --workspace-id "workspace-uuid"
# Import definition
paw projects import --file ./export.json --project-id "new-project-uuid"
```
## Related Commands
* [Projects](./projects) - Create projects within workspaces
* [Authentication](./authentication) - Manage authentication for workspace access
# Development
Source: https://docs.fusioncat.dev/development
Preview changes locally to update your docs
**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.
Please upgrade to `docs.json` before proceeding and delete the legacy `mint.json` file.
Follow these steps to install and run Mintlify on your operating system:
**Step 1**: Install Mintlify:
```bash npm
npm i -g mintlify
```
```bash yarn
yarn global add mintlify
```
**Step 2**: Navigate to the docs directory (where the `docs.json` file is located) and execute the following command:
```bash
mintlify dev
```
A local preview of your documentation will be available at `http://localhost:3000`.
### Custom Ports
By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. To run Mintlify on port 3333, for instance, use this command:
```bash
mintlify dev --port 3333
```
If you attempt to run Mintlify on a port that's already in use, it will use the next available port:
```md
Port 3000 is already in use. Trying 3001 instead.
```
## Mintlify Versions
Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI:
```bash npm
npm i -g mintlify@latest
```
```bash yarn
yarn global upgrade mintlify
```
## Validating Links
The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
```bash
mintlify broken-links
```
## Deployment
Unlimited editors available under the [Pro
Plan](https://mintlify.com/pricing) and above.
If the deployment is successful, you should see the following:
## Code Formatting
We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
## Troubleshooting
This may be due to an outdated version of node. Try the following:
1. Remove the currently-installed version of mintlify: `npm remove -g mintlify`
2. Upgrade to Node v19 or higher.
3. Reinstall mintlify: `npm install -g mintlify`
Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again.
Curious about what changed in the CLI version? [Check out the CLI changelog.](https://www.npmjs.com/package/mintlify?activeTab=versions)
# Concepts
Source: https://docs.fusioncat.dev/essentials/concepts
Definitions of the key components and entities used in Fusioncat
This glossary defines the key terms you’ll encounter when working with Fusioncat.
Use it as a quick reference to understand how schemas, messages, servers,
resources, applications, projects, and workspaces fit together in logical order
from the smallest building blocks to the containers that encapsulate them.
# Overview
Overview
Below is the list of glossary entries in the order they build on each other:
* Data schema
* Message
* Server
* Resources
* Application
* Consumer
* Producer
* Project
* Workspaces
# Glossary
## Data schema
A formal definition of the structure and data types within a payload.
Fusioncat is designed to support three schema technologies—JSONSchema,
Avro, and Protobuf—but currently only **JSONSchemas** are implemented.
**Versioning**.
Every change to a schema yields a new version, numbered sequentially starting at 1.
## Message
A communication asset that carries data according to a particular schema version. Each message includes:
* A name and human-readable description.
* A reference to a specific schema and its version.
* Its own version number for tracking changes to the message metadata or payload structure.
**Note**: One schema can be used by multiple messages.
## Server
Software or infrastructure that routes messages between producers and consumers. Examples include:
* Kafka brokers
* AMQP (RabbitMQ) servers
* MQTT brokers
* Simple setups using database tables or webhooks
* A server can host multiple resources.
## Resources
Access points through which messages flow inside a server. Depending on server type, a resource might be one of:
* Kafka topic
* AMQP exchange or queue
* MQTT topic
* Database table
* Webhook endpoint
Each resource:
* Belongs to exactly one server.
* Has one of four modes: `read`, `write`, `readwrite`, or `bind`.
* The bind mode (AMQP-specific) links exchanges to queues.
* Uses a naming convention that fully qualifies its server, mode, and identifier,
for example: `async+amqp://mainrmq@read/queue/paymentqueue`
## Application
A computer program built on the Fusioncat stack that receives and/or sends messages.
* Consumer
* The component responsible for receiving incoming messages.
* Defined by a list of message-and-resource pairs from which it reads.
* Producer
* The component responsible for sending messages.
* Defined by a list of message-and-resource pairs to which it writes.
## Project
A self-contained package that stores all schemas, messages, servers, resources, and applications.
* Everything in Fusioncat lives in a project.
* In future releases, projects will be able to reference artifacts in other projects.
## Workspaces
Top-level containers for organizing multiple projects and teams.
* A workspace typically includes several engineers.
* Engineers have access controls scoped to the projects within their workspace.
# Project file
Source: https://docs.fusioncat.dev/essentials/project_file
This section describes the fcproject.yaml file—the primary import/export format for defining, validating, and migrating an entire Fusioncat project architecture as plain text.
# Overview
Using `fcproject.yaml`, you can:
* Design your project topology (schemas, messages, servers, resources, apps) in a single file.
* Validate entity names, uniqueness, and cross-references before provisioning.
* Import definitions into Fusioncat to automatically create or update artifacts.
* Export your live project state (with UUIDs) for backup, code generation, or migration.
* Bundle builds (predefined object sets and versions) into portable, attachable manifests.
# File structure
```yaml
# Provision file version
version:
# Parameters only used during **export** operations
export_parameters:
include_export_parameters: # Embed this export_parameters block in output
servers: # Include server definitions in output
apps: # Include application definitions
messages: # Include messages
schemas: # Include schemas
include_only_latest_schema_versions: # If true, include only the latest version of each schema
include_only_schemas_used_in_messages: # If true, include only schemas referenced by messages
include_descriptions: # Include description fields for all entities
# Server definitions and their resources
servers:
- name:
type:
description:
resources: [...]
binds: [...]
# Schema definitions (only JSONSchema supported today)
schemas:
- name:
type: jsonschema
version:
description:
schema: # or example:
# Message definitions
messages:
- name:
description:
schema:
name:
version:
# Application definitions
apps:
- name:
description:
receives: [...] # consumer bindings
sends: [...] # producer bindings
```
# Top-Level Fields
* `version` Integer indicating the fcproject file format version.
Incremented when YAML structure or validation rules change.
* `export_parameters` **(export only)** Controls which parts of the project are included when exporting.
Each boolean flag toggles inclusion of that section in the output YAML.
* `include_export_parameters`: if true, the export\_parameters block itself appears in the exported file.
* `servers / apps / messages / schemas`: include the corresponding top‑level lists.
* `include_only_latest_schema_versions`: when true, only the highest-numbered version for each schema is exported.
* `include_only_schemas_used_in_messages`: when true, export only schemas referenced by messages.
* `include_descriptions`: include description fields for entities throughout the export.
* `servers` A list of server blocks. Each server must have:
* `name`: unique within the project.
* `type`: protocol identifier (async+kafka, async+amqp, async+webhook, etc.).
* `description`: human-readable label.
* `resources`: array of resources (topics, queues, exchanges, endpoints).
* `binds` (optional): AMQP-specific bindings linking exchanges to queues.
* Resource fields:
* `name`: unique under this server.
* `mode`: one of read, write, readwrite, or bind.
* `type`: resource kind (topic, queue, exchange, endpoint, table).
* `description`: free-form text.
* `schemas` A list of schema definitions. Each schema block includes:
* `name`: unique identifier.
* `type`: currently only jsonschema.
* `version`: sequential integer, starting at 1.
* `description`: optional summary.
* `schema`: the JSONSchema document as a string, or
* `example`: a JSON instance conforming to the schema.
* `messages` A list of message definitions. Each message has:
* `name`: unique within project.
* `description`: what the message conveys.
* `schema`: a nested block referencing
* `name`: schema name
* `version`: optional (defaults to the latest version).
* `apps` A list of application definitions. Each application block contains:
* `name`: unique identifier.
* `description`: application purpose.
* `receives` (optional): array of \[ message, resource ] pairs the app consumes.
* `sends` (optional): array of \[ message, resource ] pairs the app produces.
# Key Rules & Conventions
* Uniqueness: All `name` fields (servers, resources, schemas, messages, apps)
must be unique within a single project. They can contan latin alphabet leters, digits and \_ symbol.
* UUID Assignment:
* Imported definitions lack UUIDs.
* Exported or live entities always include a uuid property.
* Presence of a UUID means the resource already exists in its target server.
* Scoped Definitions:
* All resources, schemas, messages, and apps defined in fcproject.yaml must belong to the same project.
# Example snippet
```yaml
version: 1
servers:
- name: mainkafka
type: async+kafka
description: "Primary Kafka cluster"
resources:
- name: emails
mode: readwrite
type: topic
description: "Email message topic"
schemas:
- name: email_schema
type: jsonschema
version: 1
description: "Email payload format"
schema: >
{
"type": "object",
"properties": {
"to": { "type": "string" },
"body": { "type": "string" }
},
"required": ["to", "body"]
}
messages:
- name: send_email
description: "Trigger email dispatch"
schema:
name: email_schema
apps:
- name: mailer
description: "Service that sends emails"
receives:
- message: send_email
resource: async+kafka://mainkafka@readwrite/topic/emails
```
# Fusioncat
Source: https://docs.fusioncat.dev/index
Build event-driven applications with schema-first development
Fusioncat is currently in its alpha stage. The main API server is located at:
[https://api.staging.fusioncatalyst.io/](https://api.staging.fusioncatalyst.io/)
Please note that breaking changes and bugs are to be expected, as the product is still under active development.
## What is Fusioncat?
Fusioncat is a schema-first development platform that simplifies building event-driven and asynchronous applications. It provides a unified approach to managing complex distributed systems by centralizing schema definitions, versioning, and code generation across multiple programming languages.
Think of Fusioncat as the "single source of truth" for all your API contracts, message formats, and event definitions - ensuring consistency across your entire technology stack.
## Why Async Communication Matters
In modern software architecture, asynchronous communication has become critical for building scalable, resilient applications. Here's why:
### 🚀 **Scalability**
Async systems can handle thousands of concurrent operations without blocking, allowing your applications to scale horizontally with demand.
### 🛡️ **Resilience**
When services communicate asynchronously, temporary failures don't cascade through your system. Messages can be queued and processed when services recover.
### ⚡ **Performance**
Non-blocking operations mean your services can process multiple requests simultaneously, dramatically improving throughput and reducing latency.
### 🔄 **Decoupling**
Services don't need to know about each other's implementation details - they only need to understand the message contracts, enabling independent deployment and scaling.
## The Fusioncat Advantage
### 1. **Schema-First Development**
Define your data structures once, and Fusioncat ensures consistency across all services, languages, and teams. No more schema drift or version mismatches.
### 2. **Multi-Protocol Support**
Whether you're using Kafka for event streaming, RabbitMQ for task queues, or webhooks for external integrations, Fusioncat provides a unified interface.
### 3. **Automatic Code Generation**
Stop writing boilerplate code. Fusioncat generates type-safe models, serializers, and client libraries in TypeScript, Python, Java, and Go.
### 4. **Version Management**
Schema evolution is inevitable. Fusioncat's built-in versioning ensures backward compatibility while allowing your APIs to evolve.
## Real-World Use Cases
Handle order processing, inventory updates, and payment notifications across multiple services without tight coupling
Process transactions, risk assessments, and compliance checks asynchronously for better performance and reliability
Manage millions of device events, telemetry data, and command dispatching with event-driven architecture
Coordinate video processing, content delivery, and user analytics through message-driven workflows
## Quick Start
Get started in minutes with our command-line interface
Explore all available commands and options
### Your First Fusioncat Project
```bash
# 1. Install the Paw CLI
curl -L https://github.com/fusioncatltd/paw/releases/latest/download/paw_$(uname -s)_$(uname -m).tar.gz | tar xz
sudo mv paw /usr/local/bin/
# 2. Initialize and authenticate
paw init-settings-file --server https://api.staging.fusioncatalyst.io --language go
paw auth signup --email your@email.com --password yourpassword
export FC_ACCESS_TOKEN="your-auth-token"
# 3. Create your first project
paw projects new --name "My Event-Driven App" --belongs-to user
```
## Core Concepts
Organize your schemas and applications with projects and team workspaces
Define your data structures with JSON Schema and automatic versioning
Create concrete message types from schemas for events, commands, and APIs
Generate type-safe code in multiple languages from your definitions
## Architecture Patterns
Fusioncat supports modern architectural patterns out of the box:
### Event-Driven Architecture
* **Event Sourcing**: Capture all changes as a sequence of events
* **CQRS**: Separate read and write models for optimal performance
* **Saga Orchestration**: Coordinate complex workflows across services
### Microservices Communication
* **Async APIs**: Define contracts for service-to-service communication
* **Message Brokers**: Integrate with Kafka, RabbitMQ, and more
* **API Gateway**: Generate unified API definitions
### Real-Time Systems
* **Event Streaming**: Process high-volume data streams
* **Webhooks**: Integrate with external services
* **WebSocket Support**: Build real-time user interfaces
## Why Choose Fusioncat?
### For Developers
* 🎯 **Type Safety**: Never worry about message format mismatches
* 🔄 **DRY Principle**: Define once, use everywhere
* 🛠️ **Developer Experience**: Modern CLI with intuitive commands
### For Teams
* 👥 **Collaboration**: Shared workspaces and projects
* 📊 **Governance**: Centralized schema management
* 🔍 **Visibility**: Track schema usage and dependencies
### For Enterprises
* 🏢 **Scalability**: Handle millions of messages per second
* 🔒 **Security**: Built-in authentication and access control
* 📈 **Evolution**: Manage API lifecycle with versioning
## Next Steps
Understand the core concepts of Fusioncat
Follow step-by-step guides to build your first app
Explore the Fusioncat API in detail
Learn patterns for production-ready applications
## Join the Community
Building the future of event-driven development requires a community. Join us:
* 🌟 [Star us on GitHub](https://github.com/fusioncatltd)
* 💬 [Join our Discord](https://discord.gg/fusioncat)
* 🐦 [Follow on Twitter](https://twitter.com/fusioncat)
* 📧 [Contact Support](mailto:support@fusioncatalyst.io)
***
*Fusioncat - zero-chaos async services management.*
# Open Source
Source: https://docs.fusioncat.dev/open-source
Deploy and run Fusioncat on your own infrastructure
## Overview
Fusioncat is available as an open-source solution that you can deploy and run on your own infrastructure. This gives you complete control over your data, customization options, and the ability to contribute to the project's development.
The open-source version includes all core features for managing asynchronous messaging architectures.
## Why Self-Host Fusioncat?
Your data never leaves your infrastructure. Perfect for organizations with strict compliance requirements.
Modify and extend Fusioncat to meet your specific needs. Add custom protocols, templates, or integrations.
## Quick Start
Get Fusioncat running in under 5 minutes using Docker.
### Prerequisites
Before you begin, ensure you have:
* Docker installed on your system
* PostgreSQL 13+ database (or use Docker Compose with included PostgreSQL)
### Installation Methods
The fastest way to get started with Fusioncat.
```bash
# Pull the latest Fusioncat image
docker pull ghcr.io/fusioncatltd/fusioncat:latest
# Run Fusioncat with your PostgreSQL database
docker run -d \
--name fusioncat \
-p 8080:8080 \
-e PG_HOST=your-postgres-host \
-e PG_PORT=5432 \
-e PG_USER=your-db-user \
-e PG_PASSWORD=your-db-password \
-e PG_DB_NAME=fusioncat \
-e JWT_SECRET=your-secret-key \
ghcr.io/fusioncatltd/fusioncat:latest
```
Replace the database credentials with your actual PostgreSQL connection details.
Verify the installation:
```bash
curl http://localhost:8080/health
```
You should see:
```json
{
"status": "healthy",
"service": "fusioncat"
}
```
For a complete setup including PostgreSQL, use Docker Compose.
Create a file named `docker-compose.yml`:
```yaml
version: '3.8'
services:
fusioncat:
image: ghcr.io/fusioncatltd/fusioncat:latest
ports:
- "8080:8080"
environment:
PG_HOST: postgres
PG_PORT: 5432
PG_USER: fusioncat
PG_PASSWORD: ${DB_PASSWORD}
PG_DB_NAME: fusioncat
JWT_SECRET: ${JWT_SECRET}
depends_on:
- postgres
restart: unless-stopped
postgres:
image: postgres:15-alpine
environment:
POSTGRES_USER: fusioncat
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_DB: fusioncat
volumes:
- postgres_data:/var/lib/postgresql/data
restart: unless-stopped
volumes:
postgres_data:
```
Create an `.env` file with your secrets:
```bash
DB_PASSWORD=your-secure-password
JWT_SECRET=your-jwt-secret-key
```
Start the services:
```bash
docker-compose up -d
```
Both Fusioncat and PostgreSQL will start automatically and restart if they crash.
For development or customization, build Fusioncat from source.
**Prerequisites:**
* Go 1.23+
* Node.js 18+ (for quicktype)
* PostgreSQL 13+
* Make
Clone and build:
```bash
# Clone the repository
git clone https://github.com/fusioncatltd/fusioncat.git
cd fusioncat
# Copy and configure environment
cp .env.template .env
# Edit .env with your database credentials
# Install dependencies
go mod download
npm install -g quicktype
# Run locally
make run
# Or build Docker image
make docker-build
```
For development with hot reload:
```bash
go install github.com/cosmtrek/air@latest
air
```
## Configuration
Fusioncat is configured through environment variables. Here are the key settings:
| Variable | Description | Default | Required |
| ------------- | ----------------------- | ---------------------------------------------- | -------- |
| `PG_HOST` | PostgreSQL host address | localhost | ✅ |
| `PG_PORT` | PostgreSQL port | 5432 | ✅ |
| `PG_USER` | Database username | - | ✅ |
| `PG_PASSWORD` | Database password | - | ✅ |
| `PG_DB_NAME` | Database name | fusioncat | ✅ |
| `PG_SSLMODE` | PostgreSQL SSL mode | require | ❌ |
| `JWT_SECRET` | Secret for JWT tokens | - | ✅ |
| `ADMIN_URL` | Admin panel URL | [http://localhost:3000](http://localhost:3000) | ❌ |
Always use strong, unique values for `JWT_SECRET` and `PG_PASSWORD` in production.
## First Steps After Installation
Once Fusioncat is running, you can start using it immediately:
### 1. Create Your First User
```bash
curl -X POST http://localhost:8080/v1/public/users \
-H "Content-Type: application/json" \
-d '{
"email": "admin@example.com",
"password": "SecurePassword123!"
}'
```
### 2. Authenticate
```bash
curl -X POST http://localhost:8080/v1/public/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "admin@example.com",
"password": "SecurePassword123!"
}'
```
Save the returned JWT token for authenticated requests.
### 3. Create Your First Project
```bash
curl -X POST http://localhost:8080/v1/protected/projects \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "My Messaging System",
"description": "Production messaging architecture"
}'
```
### 4. Access the API Documentation
Open your browser and navigate to:
```
http://localhost:8080/swagger/index.html
```
This provides interactive API documentation for all available endpoints.
## Architecture Overview
Understanding Fusioncat's architecture helps you deploy and scale it effectively.
```mermaid
graph TB
subgraph "Your Infrastructure"
FC[Fusioncat API Server]
PG[(PostgreSQL Database)]
subgraph "Your Services"
S1[Service A]
S2[Service B]
S3[Service C]
end
subgraph "Message Brokers"
K[Kafka]
R[RabbitMQ]
M[MQTT]
end
end
FC --> PG
FC -.->|Generates Code| S1
FC -.->|Generates Code| S2
FC -.->|Generates Code| S3
S1 <--> K
S2 <--> R
S3 <--> M
```
### Key Components
* **API Server**: RESTful API for managing projects, schemas, and code generation
* **PostgreSQL**: Stores all configuration, schemas, and project metadata
## Security Considerations
When self-hosting Fusioncat, consider these security best practices:
Deploy Fusioncat behind a reverse proxy (nginx, Traefik) with SSL/TLS certificates.
* Use strong passwords
* Enable SSL for database connections
* Restrict network access to PostgreSQL
Deploy in a private network segment, accessible only to authorized services.
Keep Fusioncat updated to the latest version for security patches.
```bash
docker pull ghcr.io/fusioncatltd/fusioncat:latest
```
Regularly backup your PostgreSQL database containing all your schemas and configurations.
## Monitoring & Observability
Monitor your Fusioncat deployment for optimal performance:
### Health Checks
The `/health` endpoint provides basic health status:
```bash
curl http://localhost:8080/health
```
### Logging
Fusioncat logs to stdout/stderr, compatible with any log aggregation system:
```bash
docker logs fusioncat
```
## Upgrading Fusioncat
To upgrade to a new version:
```bash
# Pull the latest image
docker pull ghcr.io/fusioncatltd/fusioncat:latest
# Stop the current container
docker stop fusioncat
docker rm fusioncat
# Start with the new version
docker run -d \
--name fusioncat \
-p 8080:8080 \
[...your environment variables...] \
ghcr.io/fusioncatltd/fusioncat:latest
```
```bash
# Pull the latest image
docker-compose pull
# Restart services
docker-compose up -d
```
```bash
# Update the deployment
kubectl set image deployment/fusioncat \
fusioncat=ghcr.io/fusioncatltd/fusioncat:latest
# Watch the rollout
kubectl rollout status deployment/fusioncat
```
Database migrations are handled automatically on startup. Always backup your database before major upgrades.
## Contributing
Fusioncat is open source and welcomes contributions!
### Get Involved
* **GitHub Repository**: [github.com/fusioncatltd/fusioncat](https://github.com/fusioncatltd/fusioncat)
* **Report Issues**: [GitHub Issues](https://github.com/fusioncatltd/fusioncat/issues)
* **Submit Pull Requests**: Fork, improve, and contribute back
### Development Setup
```bash
# Fork and clone
git clone https://github.com/YOUR-USERNAME/fusioncat.git
cd fusioncat
# Create feature branch
git checkout -b feature/amazing-feature
# Make changes and test
make test
# Submit pull request
```
## Support
Comprehensive guides and API reference
Report bugs and request features
## License
Fusioncat is licensed under the Apache 2 License, giving you freedom to use, modify, and distribute it in your projects.
***
Ready to get started? [Install Fusioncat](#quick-start) now or explore our [API documentation](/api-reference/introduction) to learn more.
# Quickstart
Source: https://docs.fusioncat.dev/quickstart
Start building awesome documentation in under 5 minutes
## Setup your development
Learn how to update your docs locally and deploy them to the public.
### Edit and preview
During the onboarding process, we created a repository on your Github with
your docs content. You can find this repository on our
[dashboard](https://dashboard.mintlify.com). To clone the repository
locally, follow these
[instructions](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
in your terminal.
Previewing helps you make sure your changes look as intended. We built a
command line interface to render these changes locally.
1. Install the
[Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the
documentation changes locally with this command: `npm i -g mintlify`
2. Run the following command at the root of your documentation (where
`docs.json` is): `mintlify dev`
If you’re currently using the legacy `mint.json` configuration file, please update the Mintlify CLI:
`npm i -g mintlify@latest`
And run the new upgrade command in your docs repository:
`mintlify upgrade`
You should now be using the new `docs.json` configuration file. Feel free to delete the `mint.json` file from your repository.
### Deploy your changes
Our Github app automatically deploys your changes to your docs site, so you
don't need to manage deployments yourself. You can find the link to install on
your [dashboard](https://dashboard.mintlify.com). Once the bot has been
successfully installed, there should be a check mark next to the commit hash
of the repo.
[Commit and push your changes to
Git](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push)
for your changes to update in your docs site. If you push and don't see that
the Github app successfully deployed your changes, you can also manually
update your docs through our [dashboard](https://dashboard.mintlify.com).
## Update your docs
Add content directly in your files with MDX syntax and React components. You can use any of our components, or even build your own.
Add content to your docs with MDX syntax.
Add code directly to your docs with syntax highlighting.
Add images to your docs to make them more engaging.
Add templates to your docs to make them more reusable.