PRESS2PIXEL
Product docs

Documentation

press2pixel turns a website into campaign-ready social media assets. This page documents the app itself: crawler, brand extraction, AI grouping, template rendering and editing, planner, imports and exports, social integrations, API, persistence, auth, and deployment.

Book a demo Open the app
Start

Quick start

Run the app, paste a website URL, and let the server build a reusable customer workspace. The first crawl creates the database rows, corporate identity context, campaigns, and live previews.

  • Install dependencies with npm install, then start the Express server with npm start.
  • Open http://localhost:3000 or the configured reverse-proxy host.
  • Paste a domain. press2pixel resolves redirects, extracts brand signals, crawls content, groups campaigns, and stores the result.
  • Refreshes keep the same customer, selected templates, captions, and design settings through SQLite and localStorage.
npm install
npm start
# open http://localhost:3000
Use the hosted app at app.press2pixel.fun, or run the same Node/Electron app locally during development.
Output

What the app builds

The product is a bulk social media asset generator. It turns posts, pages, products, events, listings, and other structured content into branded image sets and matching captions.

  • Campaign-ready PNG graphics across practical social ratios.
  • Lazy AI captions for Twitter/X, Instagram, and LinkedIn, stored per content row.
  • ZIP exports, import/export utilities, and fullscreen signage playlists.
  • Universal templates plus customer-locked signature templates that only appear for matching hosts.
  • A template editor for JSON templates, live previews, and saved custom designs.
  • A project planner that shows upcoming background syncs and running refreshes.
Template availability is dynamic: universal styles, customer-locked signatures, and custom templates are loaded from the active app registry instead of a fixed public count.
Crawler

Website ingestion pipeline

Crawling happens on the server so the browser stays presentational and avoids CORS problems. The crawler tries structured sources first, then supplements them with sitemap-driven page extraction.

  • resolveCanonical follows http/https redirects and normalizes the customer host.
  • extractCI collects logo, brand color, fonts, language, hero image, social handles, and contact signals.
  • WordPress REST and Shopify JSON are read when available.
  • sitemap.xml, robots Sitemap entries, llms.txt, JSON-LD, Open Graph, and rendered SPA HTML fill the gaps.
  • Rendered DOM images, srcset candidates, lazy images, inline background images, and computed CSS background images are extracted before scoring.
  • Media candidates are scored so hero, cover, and page-matching images beat icons, thumbnails, and generic logos.
POST /api/crawl/:urlId
  -> resolveCanonical()
  -> extractCI()
  -> wpScrape() / shopifyScrape()
  -> discoverUrls()
  -> extractFromPage()
  -> groupItems()
  -> persist
JavaScript-heavy pages can be rendered with Playwright when the static HTML looks like an empty hydration shell.
Backend

API surface

The frontend talks to a compact Express API. URL workspaces, content, campaigns, sync state, auth, captions, provider status, templates, logs, and config routes are all served from the Node app.

  • POST /api/crawl/:urlId runs the full sync pipeline for a saved URL workspace.
  • GET /api/urls, /api/content/:urlId, and /api/campaigns/:urlId hydrate the workspace.
  • POST /api/captions/generate writes generated caption JSON back to content.captions.
  • GET /api/events streams sync updates over Server-Sent Events.
  • GET /api/sync-schedule feeds the Task Manager and project Planner calendar.
  • Auth, OAuth, settings, provider, custom-template, social-import, token, log, and system-stat routes support the app shell.
GET    /api/urls
POST   /api/urls
POST   /api/crawl/:urlId
GET    /api/content/:urlId
GET    /api/campaigns/:urlId
POST   /api/captions/generate
POST   /api/social/import
GET    /api/sync-schedule
GET    /api/events
Data

Content model and storage

Every discovered item is normalized before it reaches the UI. A stable id_unique key deduplicates content across syncs, while raw_json keeps enough source detail for media repair and diagnostics.

  • urls store the canonical URL, display name, corporate identity JSON, design preset JSON, language settings, per-URL crawl limit, and last sync time.
  • content stores title, excerpt, imageUrl, date, type, source_url, raw_json, campaign_id, and captions.
  • campaigns store AI or heuristic groups per URL workspace.
  • crawl_cache keeps fetched pages for a six-hour TTL, reducing repeated network work.
  • sync_log records started/completed times, status, item counts, and errors.
  • Custom templates, OAuth tokens, contacts, socials, logs, and provider metadata live in dedicated tables.
content {
  id_unique,
  url_id,
  type,
  title,
  excerpt,
  imageUrl,
  image_alts,
  source_url,
  campaign_id,
  captions
}
AI

AI routing, grouping, and captions

AI runs through local Ollama or command-line providers rather than direct browser calls. Each task has its own provider chain, model settings, fallback behavior, and provenance.

  • Campaign grouping is local-first through Ollama, with a deterministic taxonomy fallback when the model is unavailable.
  • Caption generation uses a server route, saves provider/model metadata, and reuses stored captions on export.
  • Template and vision generation can use Gemini, Claude, Codex, MLX, or Ollama depending on the configured task chain.
  • Rate-limit state and token usage are tracked so the app can skip temporarily unavailable providers.
CAPTION_PROVIDERS=claude,gemini
GROUPING_PROVIDERS=ollama,gemini,claude
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=gemma4:26b
Captions are generated in the same language as the source item whenever the model can infer it.
Renderer

Templates and design controls

Templates are JSON files rendered by the frontend. The app keeps template markup separate from app logic and uses a strict root token contract so every design responds to the same controls.

  • New templates live under assets/json/templates and are activated through index.json.
  • The in-app template editor can create and update custom JSON templates with live preview validation.
  • Template variables cover title, excerpt, image, brand colors, typography, spacing, shadows, surfaces, and export ratio behavior.
  • Font sizes use em units so separate headline and body sliders can scale typography reliably.
  • Image fit and position are bound through object-fit and object-position controls.
  • Brand templates use customerHosts to appear only for the matching customer domain.
  • Element-level toggles and text overrides let teams adjust one post or template without changing the whole workspace.
font-size:100%;--p2p-headline-mul:{{headlineScale}};--p2p-text-mul:{{textScale}}
The shared template-base.css contract keeps newer templates visually consistent while still allowing expressive brand signatures.
Persistence

Database, backups, and sync

The app uses a small database facade. SQLite is the default, while MariaDB/MySQL can be selected through DB_DRIVER without changing the rest of the codebase.

  • scripts/db/index.js exposes run, all, get, and migrate for every module.
  • Migrations are idempotent and create the active driver schema on boot.
  • npm run db:backup exports JSONL table snapshots and can import them later.
  • npm run db:sync copies data between SQLite and MariaDB/MySQL.
  • node-cron runs background sync and skips URL workspaces that were synced recently.
  • Production sync jobs can write to MariaDB/MySQL directly when DB_DRIVER points at the production database.
DB_DRIVER=sqlite
# or
DB_DRIVER=mariadb
DB_HOST=127.0.0.1
DB_NAME=press2pixel
Ops

Deploy with Docker or reverse proxy

The app can run directly with Node or through Docker Compose. A production proxy should send every app request to Node because the server owns API routes and view composition.

  • docker compose up -d starts the app plus an Ollama sidecar.
  • BYO Ollama deployments can point OLLAMA_URL at the host or another container.
  • Nginx and Apache examples proxy all app routes to http://127.0.0.1:3000.
  • The production image intentionally excludes Playwright/Chromium and cloud CLIs unless a custom image adds them.
  • Electron packaging can run the same Express app locally for desktop use.
docker compose up -d
docker compose exec ollama ollama pull gemma4:26b
Security

Auth, privacy, and safety notes

The app includes session authentication, optional OAuth providers, owner-scoped URL access, and admin bootstrap support. Public deployments should pair auth with HTTPS, rate limits, secure headers, and careful crawl limits.

  • AUTH_ENABLED=true activates the login gate and session-protected API routes.
  • Passwords use scrypt and sessions are stored as opaque HttpOnly-cookie tokens.
  • OAuth buttons appear only when provider client IDs and secrets are configured.
  • Social imports can pull recent posts from connected providers into the same content model as crawled website items.
  • Open registration should be replaced with approval or invite codes before broad public use.
  • Public deploy should enforce HTTPS and rate-limit crawl, AI, login, and registration routes.
AUTH_ENABLED=true
ADMIN_EMAIL=info@example.com
ADMIN_PASSWORD=change-me
Roadmap

Quality gates and roadmap

The app includes automated tests, template audits, sync logs, provider status, token tracking, and a Task Manager for runtime diagnostics.

  • npm test runs the template audit and validates active template JSON, renderer tokens, image controls, conditionals, and customer host coverage.
  • Runtime diagnostics expose sync progress, recent logs, provider status, token usage, scheduled refreshes, and host resource stats.
  • Template audits validate active JSON, required renderer tokens, image controls, conditionals, and host restrictions.
  • Unit tests cover auth logic, database migration, template validation, renderer interpolation, token tracking, and provider config.
npm run test:unit
npm run test:audit
npm test
For implementation-level detail, the app keeps dedicated docs for API behavior, AI routing, database drivers, Docker deployment, auth, and templates.