Bristol Carousel

Bristol Carousel is a format-first carousel studio for local newsletters, local media outlets, community publishers, and city-focused creators.

It helps editors turn recurring local information, starting with Bristol events roundups, into reviewable Instagram carousel assets without rebuilding every slide manually in Canva.

Current Build

The repository currently includes a working Next.js foundation for the Events Roundup MVP:

• Format library route for choosing the controlled Events Roundup format
• Source intake and review components for messy or structured event material
• Editable source-item cards with image attachment support
• SVG-backed slide preview components
• Sharp-powered export route coverage for PNG/JPG carousel assets
• Convex schema/functions for workspaces, formats, source items, assets, slides, and exports
• Vitest, Convex, render, text-fit, and Playwright coverage for the core flow

Saved project workspaces require Convex environment variables. Without Convex configured, the static routes still render and the tests cover the intended creation path.

The core product use case is simple: turn structured local information into polished carousel content, such as:

• 10 events happening in Bristol this weekend
• 7 new restaurants to try this month
• 5 planning decisions residents should know about
• A weekly culture roundup
• A neighbourhood guide
• A matchday, market, festival, or public-meeting preview

The goal is to help small editorial teams publish useful, repeatable social content without manually designing every slide from scratch.

Who It Is For

Bristol Carousel is designed for teams and individuals who regularly turn local information into visual social posts:

• Local newsletters
• Local newspapers and digital media outlets
• Events curators
• Community organisations
• Tourism and culture teams
• Independent city guides
• Social media editors
• Local creators and reporters

Although the initial focus is local media, the same workflow can support other recurring formats, including product roundups, internal comms, campaign explainers, educational posts, and niche community updates.

What It Does

The app helps users move from raw information to a ready-to-post Instagram carousel.

At a high level, the workflow is:

1. Add or import source content.
2. Choose a carousel format.
3. Generate slide copy.
4. Apply a visual template.
5. Review and edit the carousel.
6. Export images for Instagram or other social platforms.

Core Features

• Carousel generation: Create multi-slide posts from a list of events, stories, places, recommendations, or announcements.
• Local-media templates: Use repeatable formats such as event roundups, weekend guides, explainers, venue lists, and news summaries.
• Editorial controls: Edit titles, descriptions, ordering, dates, locations, calls to action, and source notes before export.
• Brand styling: Reuse colours, fonts, logos, spacing, and slide layouts so posts feel consistent.
• Image support: Add event images, venue photos, maps, or default visual treatments where no image is available.
• Export-ready output: Produce square or portrait carousel slides suitable for Instagram and other platforms.
• Reusable formats: Save formats that match common recurring posts, such as "10 events in Bristol" or "This week in the city".

Example Carousel Formats

10 Events In The City

A roundup carousel for newsletters and local media teams publishing weekly or weekend event guides.

Typical slides:

1. Cover slide
2. Event 1
3. Event 2
4. Event 3
5. Event 4
6. Event 5
7. Event 6
8. Event 7
9. Event 8
10. Final call-to-action slide

Weekend Guide

A more editorial format for city guides, combining events, food, culture, and family-friendly recommendations.

Local News Explainer

A carousel that turns one local story into a sequence of short, readable slides.

Venue Or Business Roundup

A format for posts like "8 independent cafes to try", "New openings this month", or "Best places for live music".

Inputs

Depending on the final implementation, the app may support:

• Manual entry
• CSV uploads
• Newsletter drafts
• Website URLs
• Event listings
• Airtable or Google Sheets
• CMS exports
• Social captions or rough notes

Each item can include fields such as title, date, time, location, description, price, image, URL, category, and source.

Outputs

The app should export carousel assets that are ready for publishing:

• PNG or JPG slide images
• Editable project files
• Suggested Instagram captions
• Alt text
• Hashtags
• Source links or credits

Product Principles

• Make local information easier to share: The app should help publishers turn useful information into formats people actually read and save.
• Keep editorial control: Automation should speed up drafting and layout, not remove human judgment.
• Respect local brands: Posts should feel like they come from the publisher, not from a generic template engine.
• Reduce repetitive design work: Recurring formats should become fast, consistent, and easy to update.
• Support small teams: The workflow should be simple enough for one editor, founder, or social media manager to use regularly.

Potential Workflow

Source content
  -> Structured items
  -> Carousel format
  -> Generated slide copy
  -> Branded visual template
  -> Editor review
  -> Exported carousel

Roadmap Ideas

• Template builder for recurring local media formats
• Brand kit management
• AI-assisted copy generation
• Auto-summarisation from article or event URLs
• Drag-and-drop slide editor
• Calendar-aware event sorting
• Duplicate detection across event feeds
• Caption and alt-text generation
• Multi-city support
• Team review and approval flow
• Direct scheduling or publishing integrations

Development

The app is scaffolded as a root-level TypeScript Next.js App Router project with Convex client wiring and initial test harnesses for frontend, Convex functions, Sharp-compatible SVG rendering, and Playwright browser coverage.

Installation

npm install

Environment Variables

Create local environment files as needed, but do not commit them.

NEXT_PUBLIC_CONVEX_URL=
CONVEX_DEPLOYMENT=

NEXT_PUBLIC_CONVEX_URL enables the client-side Convex provider. Without it, the app still renders the static scaffold routes so contributors can run the foundation before connecting a Convex deployment.

Running Locally

npm run dev

Then open http://localhost:3000. The root page links to /studio, which is a foundation route for later format selection, intake, SVG preview, and export work.

To configure Convex locally, run:

npm run convex:dev

Testing

npm run lint
npm run test
npm run build
npm run test:e2e

The current smoke suite covers:

• Root page rendering and navigation into the studio route.
• Convex provider availability for client components when configured.
• A Convex function smoke query through convex-test.
• Sharp reading SVG dimensions on a Node-compatible path.
• Playwright reaching the studio route from the root page.

Rendering Direction

Per the MVP plan, slide previews and exports use canonical SVG documents. The export route rasterizes those SVGs with Sharp on a Node.js runtime path rather than relying on HTML/CSS screenshot export.

Agent Guidance

Reusable product guidance for agent-assisted intake and editorial safety lives in docs/agent-guidance/:

• events-roundup-intake.md defines how the Events Roundup intake lane turns supplied source material into reviewable candidate source items.
• editorial-safety.md defines factual caution, ambiguity handling, slide-copy boundaries, image review behavior, and export-readiness principles.

These files are app-owned guidance for Bristol Carousel behavior. They are not Codex skills and should stay review-first: automation prepares structured material, while editors approve facts and final output.

Status

MVP foundation in progress. The repo is beyond concept documentation: it has the application scaffold, format-selection UI, source review components, SVG rendering/export foundations, Convex backend model, and automated coverage. The next portfolio-level milestone is a deployed demo with Convex configured and a short walkthrough of the full Events Roundup flow.