Technical Documentation

Overview

Publica Now is a creator economy platform for independent publishers in Latin America and beyond. Creators publish and sell articles, books, audio, visual art, and courses. Readers discover, purchase, and consume content directly on the platform.

Architecture

The platform follows a server-rendered architecture with Livewire single-file components. No separate frontend SPA or API layer needed for the main application.

Domain Model

External Services

Content Types

Every work has a content_type that determines its presentation, CTA labels, and delivery format.

Pricing Models

URL Structure

All public URLs are human-readable and SEO-friendly. Works are always scoped under their creator.

Slugs are auto-generated from titles using spatie/laravel-sluggable and are unique per model.

Creator API

Creators manage content through the dashboard UI. Under the hood, the platform exposes a consistent data model for potential API access.

Creator Profile

{
  "id": "01jk...",
  "name": "Pablo Laurino",
  "slug": "pablo-laurino",
  "bio": "Independent publisher from Buenos Aires.",
  "website": "https://example.com",
  "avatar_url": "https://...",
  "banner_url": "https://...",
  "store_domain": "pablo.publica.now",
  "branding": {
    "primary_color": "#ff6b35",
    "font": "inter"
  }
}

Work Object

{
  "id": "01jk...",
  "creator_id": "01jk...",
  "title": "Mi Semana",
  "slug": "mi-semana",
  "content_type": "literary",
  "format": "EPUB",
  "status": "published",
  "pricing_model": "free",
  "price_cents": 0,
  "currency": "usd",
  "description": "A weekly editorial...",
  "tags": ["editorial", "weekly", "culture"],
  "cover_image_url": "works/01jk.../cover.png",
  "view_count": 342,
  "rating_avg": 4.50,
  "rating_count": 12,
  "published_at": "2026-03-01T00:00:00Z",
  "metadata": {
    "publica_la_id": "abc123",
    "publica_la_slug": "mi-semana",
    "publica_la_reader_url": "https://publicanow.publica.la/reader/mi-semana"
  }
}

Works Lifecycle

A work progresses through distinct stages from creation to consumption.

Content Conversion Pipeline

Payments

Payments run on Stripe Checkout with Adaptive Pricing. Creators set a price in their chosen currency; Stripe presents buyers their local currency at checkout and handles the FX. The platform settles in the creator's currency.

Supported pricing currencies

Creators can price work in: USD, EUR, GBP, MXN, BRL, ARS, COP, CLP, PEN, UYU. Buyers see their local currency at checkout regardless of the creator's choice.

Payment Flow

Reader clicks "Buy" on work landing page
    |
    v
POST /checkout/{work}/pay
    |
    v
StripeService creates a Checkout Session
    |-- mode: payment | subscription
    |-- adaptive_pricing.enabled: true
    |-- price_data with creator's currency + amount
    |
    v
302 redirect to Stripe-hosted checkout (checkout.stripe.com)
    |
    v
Buyer pays in their local currency (Stripe handles FX)
    |
    v
Two parallel paths fire:
  (a) success_url → /checkout/{work}/callback
      Best-effort idempotent purchase row for instant access
  (b) checkout.session.completed webhook → ProcessStripeWebhook job
      Canonical writer; dedupes on stripe_payment_intent_id
    |
    v
FulfillPurchaseOnPublicaLa job grants reader access
    |
    v
Reader can access content in embedded reader

Content Delivery

Content is delivered through the Publica.la reader, embedded directly in the work landing page. This keeps the reading experience integrated with reviews, comments, and creator context.

Publica.la Integration

Communication with Publica.la happens via their REST API v3, authenticated with an API key (X-User-Token header).

Reader Embedding

The reader is embedded via iframe on the work show page. For authenticated users with access, the flow is:

1. ensureReadAccess(user, work)    // Create permission order if needed
2. getReaderUrl(work)               // e.g., /reader/mi-semana
3. generateAuthToken(user, url)     // JWT with intended_url
4. getSsoUrl(token)                 // Full SSO login URL
5. Render iframe with SSO URL       // User lands in reader, authenticated

The iframe uses sandbox attributes allow-same-origin allow-scripts allow-popups allow-forms for security while allowing the reader to function properly.

Authentication

Publica Now uses Laravel's built-in session authentication. For the embedded Publica.la reader, a separate JWT SSO mechanism bridges the two systems.

Platform Auth

JWT SSO (Publica.la)

When a user needs to access the embedded reader, a short-lived JWT is generated:

{
  "aud": "farfalla",
  "sub": "user",
  "iss": "publica-now",
  "exp": 1709730000,           // 60 seconds from now
  "user": {
    "uuid": "user-ulid",
    "email": "[email protected]"
  },
  "intended_url": "/reader/mi-semana",
  "reader_exit_url": "https://publica.now/creators/pablo/works/mi-semana"
}

Token is signed with HS256 using a shared secret. Expires in 60 seconds — only valid for the initial SSO redirect.

Webhooks

Publica Now receives webhooks from external services to stay in sync with payment status and content interactions.

All webhook endpoints are excluded from CSRF verification. Events are processed asynchronously via queued jobs with retry backoff (60s, 120s, 300s).

Embeds & Integrations

Publica Now supports embedding content and integrating with external systems.

Embedded Reader

The Publica.la reader is embedded directly in work pages. Authenticated users see the reader inline alongside reviews and creator info. Unauthenticated users see the cover image and a "Sign in to read" CTA.

File Storage

All files are stored on S3 and accessed via temporary signed URLs (1-hour expiry). Cover images resolve through the cover_url accessor which transparently handles both full URLs and S3 storage paths.

Queue Jobs