slices / docs / intro.md

# Introduction

Slices is an open source platform for building structured data applications on
the AT Protocol network.

## What is Slices?

Slices lets you define custom data schemas and build applications that store,
query, and sync structured records across the decentralized AT Protocol network.
Think of it as a schema-first backend that automatically handles data
validation, indexing, and cross-network synchronization.

## How Slices Works on AT Protocol

```mermaid
flowchart LR
    Users[Users<br/>Create/Update Records] --> PDS[PDS Nodes<br/>Store user data]
    PDS --> Firehose[Firehose<br/>Stream of all events]
    Firehose --> SlicesNetwork[Slices Network - AppView<br/>• Monitors all AT Protocol data<br/>• Routes to relevant slices]
    SlicesNetwork --> SliceA[Slice A<br/>• Blog lexicons<br/>• Post records<br/>• Comment queries]
    SlicesNetwork --> SliceB[Slice B<br/>• Music lexicons<br/>• Album records<br/>• Playlist queries]
    SliceA --> ClientA[Application<br/>Client<br/>• Read/write data]
    SliceB --> ClientB[Application<br/>Client<br/>• Read/write data]
```

**Flow:**

1. Users create records on their Personal Data Server (PDS)
2. The Firehose streams all network events in real-time
3. The Slices Network monitors the firehose and routes data to relevant slices
4. Each slice indexes only records matching its specific lexicons
5. Application clients connect to specific slices to read/write data

## Quick Start

Get started in under a minute:

```bash
# Install the CLI globally
deno install -g -A jsr:@slices/cli --name slices

# Initialize a new slice project
slices init my-app

# Start developing
cd my-app
deno task dev
```

The `slices init` command creates a full-stack Deno app with OAuth
authentication, automatically creates your slice on the network, and generates a
type-safe TypeScript SDK.

## Simple Example

Define a schema for vinyl albums:

```json lexicons/com/recordcollector/album.json
{
  "lexicon": 1,
  "id": "com.recordcollector.album",
  "defs": {
    "main": {
      "type": "record",
      "record": {
        "type": "object",
        "required": ["title", "artist", "releaseDate"],
        "properties": {
          "title": { "type": "string" },
          "artist": { "type": "string" },
          "releaseDate": { "type": "string", "format": "datetime" },
          "genre": { "type": "array", "items": { "type": "string" } },
          "condition": { "type": "string" }
        }
      }
    }
  }
}
```

Push your lexicon and regenerate the SDK:

```bash
# Push your lexicon to the slice
slices lexicon push

# Regenerate TypeScript SDK
slices codegen
```

Use the auto-generated, type-safe client:

```typescript
import { AtprotoClient } from "./generated_client.ts";

const client = new AtprotoClient({
  baseUrl: "https://api.slices.network",
  sliceUri: "at://your-slice-uri",
});

// Get all grunge albums
const albums = await client.com.recordcollector.album.getRecords({
  where: { genre: { contains: "grunge" } },
  sortBy: [{ field: "releaseDate", direction: "desc" }],
});
```

## Key Features

- **Schema Validation**: Define lexicons that enforce data structure and
  constraints
- **Auto-generated APIs**: REST endpoints created automatically from your
  schemas
- **TypeScript SDKs**: Type-safe clients generated from your lexicons
- **Real-time Sync**: Automatic synchronization across the AT Protocol network
- **Advanced Querying**: Filter, sort, and paginate records with a powerful
  query API
- **OAuth Built-in**: Authentication with any AT Protocol account

## When to Use Slices

Slices is ideal for:

- **Social Applications**: Build specialized communities, forums, or social
  features
- **Content Platforms**: Create blogs, documentation sites, or media libraries
- **SaaS Products**: Develop collaborative tools with structured data needs
- **Web APIs**: Design REST APIs with automatic validation and documentation
- **Decentralized Apps**: Build on AT Protocol without managing infrastructure

## Next Steps

- [Getting Started](./getting-started.md) - Set up your first slice
- [Core Concepts](./concepts.md) - Understand lexicons and collections
- [API Reference](./api-reference.md) - Explore the full API