ShutterLink Developer Back to settings
Proposal · ShutterLink for Sport Shutter

A link page for every Sport Shutter photographer

Photographers send their Instagram followers to Linktree. ShutterLink gives them a better page on sportshutter.com/@theirname: their photos, prints from their Sport Shutter shop, bookings and links. Every visit lands on Sport Shutter instead of someone else’s site.

How to read this brief. Short on time? Read The idea and How it fits, then open the simulator and use it. Building it? Chapters 4 to 10 are the spec, and the code is ready in server/.

1. The idea

Instagram allows one link in a bio. Most photographers fill it with a link-in-bio service, so their audience leaves Instagram for a generic page with no shop, no bookings and nothing to do with Sport Shutter.

ShutterLink replaces that page with one built for photographers and powered by Sport Shutter. It looks like their work, sells their prints through the Sport Shutter shop, takes bookings into their Sport Shutter inbox, and carries the Sport Shutter name to every person who taps the link.

One linkin every photographer’s bio points at sportshutter.com
Two stepsto a finished page: name, then photos from their phone
One fileplus one table and one proxy rule on Sport Shutter’s side

Why it’s worth doing

  • Traffic. Followers who tap the bio link arrive on Sport Shutter, not a third party.
  • Sales. Prints sell from the page and check out through the existing Sport Shutter shop.
  • Growth. Every page says “Powered by Sport Shutter” to an audience that already likes photography.
  • Retention. A page photographers use daily is a reason to keep their Sport Shutter account.

2. What photographers get

The page and its settings are built and working today. Use them in the simulator; the phone on the right is a live page.

A first screen that fits any phoneTheir photos full screen, name, availability and four quick buttons. Nothing cut off, no scrolling needed.
Prints from their shopSize, paper and frame with a live framed preview, a cart, then checkout on Sport Shutter.
Bookings to their inboxAn enquiry form that delivers to Sport Shutter. Their email address never appears on the page.
Gallery, film and linksA full-screen gallery, a featured video that plays in place, and their other links, in the order they choose.
Their look, not a templateEight themes or their own colours with readability checks, six type pairings, three cover styles, corner and button shapes.
Set up in two stepsTheir name, then photos straight from their phone’s library. Everything else can wait.

3. How it fits Sport Shutter

Sport Shutter keeps everything that matters: logins, data, photos, the shop and security. ShutterLink is only the front end: two web pages that ask Sport Shutter for data and send changes back. It lives at sportshutter.com/shutterlink/ through a proxy, so to visitors and photographers it is simply part of Sport Shutter.

How ShutterLink fits Sport ShutterPhotographers and visitors use the ShutterLink pages on sportshutter.com. The pages call Sport Shutter's API, where shutterlink-api.js checks the login and reads or writes the photographer's settings in Sport Shutter's database. The ShutterLink pages are hosted separately and reached through a proxy. Photographersigned in to Sport Shutter Visitortaps the link in a bio ShutterLink pageshosted separately, static files settings.htmledit your page index.htmlsportshutter.com/@name assets/data.jstalks to the API Sport Shutterowns logins, data, security Login sessionalready exists shutterlink-api.jsthe one new file Database+ one table /api
The pages never touch Sport Shutter’s database or code. Everything goes through seven API calls, answered by one file.
Built and run by the ShutterLink teamSport Shutter

Principles

  • Sport Shutter owns the data. Settings live in the photographer’s Sport Shutter profile. ShutterLink stores nothing.
  • No new login. The pages use the existing Sport Shutter session. ShutterLink never sees passwords or tokens.
  • One contract. The seven endpoints and the settings file format in this brief are the whole agreement. Each team works to it independently.
  • Nothing shared but the API. Separate code, separate hosting, separate releases.

4. What Sport Shutter adds

Most of this is wiring, not new logic. The validation, rules and responses are already written and tested in server/shutterlink-api.js; Sport Shutter connects it to its own database, storage and login.

  1. Copy one file into the server.server/shutterlink-api.js. No dependencies; Node 18 or later. Run node server/test.js to check it (38 checks).
  2. Add one table, and two small ones.Settings per photographer, old link names, and enquiries. SQL below.
  3. Write the store: five functions against that table.A PostgreSQL version is below; server/memory-store.js shows the exact behaviour.
  4. Mount it after the session middleware.Three lines in Express. It answers only /api/shutterlink/* and /api/public/pages/*.
  5. Route the pages through a proxy./shutterlink/* and /@* go to ShutterLink’s hosting. See Hosting.
  6. Add a button to the dashboard.“Edit my link page”, linking to /shutterlink/settings.html.
migrations/shutterlink.sql
create table shutterlink_profiles (
  user_id     bigint primary key references users(id) on delete cascade,
  handle      text unique,                 -- sportshutter.com/@handle
  settings    jsonb,                       -- the settings file, up to 64 KB
  revision    integer not null default 0,  -- goes up by one with every save
  updated_at  timestamptz
);

create table shutterlink_handle_aliases ( -- old names keep redirecting
  handle   text primary key,
  user_id  bigint not null references users(id) on delete cascade
);

create table shutterlink_enquiries (
  id          bigserial primary key,
  user_id     bigint not null references users(id) on delete cascade,
  name text, email text, type text, date text, msg text,
  received_at timestamptz not null default now()
);
server/shutterlink-store.js
// The five functions the API needs, backed by PostgreSQL (node-postgres).
const { Pool } = require('pg');
const pool = new Pool();

const store = {
  async getProfile(userId) {
    const { rows } = await pool.query(
      'select handle, settings, revision, updated_at from shutterlink_profiles where user_id = $1', [userId]);
    const r = rows[0];
    return r ? { handle: r.handle, settings: r.settings, revision: r.revision, updatedAt: r.updated_at } : null;
  },

  // Saves only if nobody else saved since this person loaded (revision check).
  async saveSettings(userId, settings, expected) {
    const { rows } = await pool.query(
      `insert into shutterlink_profiles (user_id, settings, revision, updated_at)
       values ($1, $2, 1, now())
       on conflict (user_id) do update
         set settings = $2, revision = shutterlink_profiles.revision + 1, updated_at = now()
         where $3::int is null or shutterlink_profiles.revision = $3
       returning revision, updated_at`, [userId, settings, expected]);
    if (!rows[0]) {
      const cur = await store.getProfile(userId);
      throw Object.assign(new Error('conflict'), { code: 'conflict', revision: cur.revision });
    }
    return { revision: rows[0].revision, updatedAt: rows[0].updated_at };
  },

  async findByHandle(handle) {
    const { rows } = await pool.query(
      `select user_id, handle from shutterlink_profiles where handle = $1
       union all
       select a.user_id, p.handle from shutterlink_handle_aliases a
         join shutterlink_profiles p using (user_id) where a.handle = $1
       limit 1`, [handle]);
    return rows[0] ? { userId: String(rows[0].user_id), handle: rows[0].handle } : null;
  },

  // Claim a new name; the old one becomes a redirect.
  async setHandle(userId, handle) {
    const c = await pool.connect();
    try {
      await c.query('begin');
      const taken = await c.query(
        'select 1 from shutterlink_handle_aliases where handle = $1 and user_id <> $2', [handle, userId]);
      if (taken.rowCount) { await c.query('rollback'); return { taken: true }; }
      const old = await c.query('select handle from shutterlink_profiles where user_id = $1 for update', [userId]);
      await c.query(`insert into shutterlink_profiles (user_id, handle) values ($1, $2)
                     on conflict (user_id) do update set handle = $2`, [userId, handle]);
      const prev = old.rows[0] && old.rows[0].handle;
      if (prev && prev !== handle)
        await c.query('insert into shutterlink_handle_aliases (handle, user_id) values ($1, $2) on conflict do nothing', [prev, userId]);
      await c.query('delete from shutterlink_handle_aliases where handle = $1 and user_id = $2', [handle, userId]);
      await c.query('commit');
      return { ok: true };
    } catch (e) {
      await c.query('rollback');
      if (e.code === '23505') return { taken: true };   // unique violation: someone else has it
      throw e;
    } finally { c.release(); }
  },

  async addEnquiry(userId, e) {
    const { rows } = await pool.query(
      `insert into shutterlink_enquiries (user_id, name, email, type, date, msg)
       values ($1, $2, $3, $4, $5, $6) returning id`, [userId, e.name, e.email, e.type, e.date, e.msg]);
    return { id: String(rows[0].id) };
  },
};

module.exports = store;
server/app.js
const express = require('express');
const { createShutterLinkApi, expressHandler } = require('./shutterlink-api');
const store = require('./shutterlink-store');

const api = createShutterLinkApi({
  store,
  images: {
    // Put the photo wherever Sport Shutter keeps images; return its public address.
    async put(userId, body, contentType) {
      const key = `shutterlink/${userId}/${Date.now()}.${contentType.split('/')[1]}`;
      await storage.upload(key, body, contentType);          // your S3, GCS or similar
      return { url: `https://images.sportshutter.com/${key}` };
    },
  },
  onEvent(type, payload) {
    if (type === 'settings.saved') cdn.purge(`/api/public/pages/${payload.handle}`);
    if (type === 'enquiry.received') notify.enquiry(payload.userId, payload.enquiryId);
  },
});

// After your session middleware, which sets req.user = { id, name }.
app.use('/api/shutterlink/images', express.raw({ type: 'image/*', limit: '8mb' }));
app.use(['/api/shutterlink', '/api/public/pages'], express.json({ limit: '100kb' }));
app.use(expressHandler(api));
Not on Express? createShutterLinkApi(...).handle(req) takes a plain object { method, path, headers, body, user, ip } and returns { status, headers, body }, so it fits any framework or a serverless function in a few lines.

5. API reference

Seven calls. All bodies are JSON except photo uploads. Errors always look like { "error": { "code", "message" } }, and the message is written to show to the photographer.

CallWhoWhat it does
GET /api/shutterlink/meSigned inWho is signed in and their link name
GET /api/shutterlink/settingsSigned inTheir settings file and revision
PUT /api/shutterlink/settingsSigned inSave the whole settings file
PUT /api/shutterlink/handleSigned inChange their link name
POST /api/shutterlink/imagesSigned inUpload a photo, get its address
GET /api/public/pages/:handleAnyoneA page’s public settings, cacheable
POST /api/public/pages/:handle/enquiriesAnyoneSend an enquiry to the photographer
GET/api/shutterlink/meSigned in
Returns200 { userId, name, handle, suggestedHandle }. handle is null until the first save; suggestedHandle is a free name based on theirs.
Errors401 signed_out: the pages show a sign-in screen.
GET/api/shutterlink/settingsSigned in
Returns200 { settings, revision, updatedAt, handle }. settings is null the first time; the pages then start from defaults with the person’s name.
PUT/api/shutterlink/settingsSigned in
Send{ settings, revision } with header X-ShutterLink: 1. revision is the one they loaded.
Returns200 { revision, updatedAt, handle }. The first save also claims a link name.
Errors409 conflict saved elsewhere since loading (the page asks which to keep) · 422 invalid_settings with errors: [{ path, message }] · 403 csrf · 429
PUT/api/shutterlink/handleSigned in
Send{ handle } with X-ShutterLink: 1
Returns200 { handle }. The old name becomes a redirect.
Errors409 taken · 422 invalid_handle (rules in Personal links)
POST/api/shutterlink/imagesSigned in
SendThe photo itself as the body, Content-Type: image/jpeg (or png, webp), with X-ShutterLink: 1. The pages shrink photos before sending.
Returns201 { url }, which the settings then refer to.
Errors413 too_large (over 8 MB) · 415 unsupported_type
GET/api/public/pages/:handleAnyone
Returns200 { handle, settings, revision, updatedAt } with private fields removed. Cache-Control: public, max-age=60, stale-while-revalidate=600.
Errors301 { movedTo } an old name: the page follows it · 404 not_found
POST/api/public/pages/:handle/enquiriesAnyone
Send{ name, email, type, date, msg }
Returns202 { ok: true }. A hidden website field catches bots: if it’s filled in, the message is quietly dropped.
Errors422 invalid_enquiry · 404 · 429 (rate limit by IP, via the rateLimit hook)

6. The settings file

Each photographer has one settings file: a JSON document holding everything about their page. The pages load it, change it, and send the whole file back to save. It’s small, about 4 KB, because photos are uploaded separately and the file holds only their addresses.

An example, shortened
{
  "v": 2,
  "profile":  { "name": "Grant Walker", "bio": "Landscapes and weddings from the Blue Mountains.",
                "location": "Katoomba, NSW", "avatar": "https://images.sportshutter.com/…",
                "status": { "on": true, "text": "Booking autumn 2027 weddings" } },
  "theme":    { "preset": "night", "colors": { "bg": "#0f1120", "surface": "#181b2e", "text": "#eef0fb", "accent": "#2326D3" },
                "font": "modern", "radius": 18, "photoTint": 65, "buttonShape": "circle", "linkStyle": "list", "align": "left" },
  "cover":    { "style": "full", "seconds": 5, "captions": true, "overlay": 55,
                "photos": [ { "url": "https://images.sportshutter.com/…", "caption": "Grose Valley, last light" } ] },
  "quick":    [ { "type": "shop", "label": "Prints" }, { "type": "enquire", "label": "Book" } ],
  "sections": [ { "id": "shop", "on": true, "title": "Prints" }, { "id": "gallery", "on": true, "title": "Recent work" } ],
  "shop":     { "featured": ["grose", "rain"], "currency": "AUD", "showPrices": true },
  "gallery":  { "columns": 3, "photos": [ … ] },
  "film":     { "url": "https://youtu.be/…", "title": "Chasing first snow", "meta": "12 min" },
  "links":    [ { "title": "Wedding portfolio", "url": "https://…", "on": true } ],
  "enquire":  { "intro": "…", "types": "Wedding, Portrait", "to": "private: never sent to visitors" },
  "socials":  { "instagram": "https://instagram.com/…" },
  "page":     { "footer": true }
}

Rules the server enforces

  • Version. v must be 2. A future format change bumps it, so old and new pages can tell files apart.
  • Size. Up to 64 KB, text fields up to 2,000 characters, and lists capped (10 cover photos, 24 gallery photos, 20 links, 4 quick buttons).
  • Links. No javascript:, vbscript: or file: addresses, and no embedded data: photos.
  • New fields are allowed. The pages can add features without a server change; the size limit keeps it honest.
  • Private fields stay private. The public call removes enquire.to (the photographer’s email) before anything leaves the server.

To see a real one, download a backup from Settings → Advanced, or open a row in the simulator’s Database tab.

7. Sign-in and security

Because the pages are served from sportshutter.com, the browser sends the photographer’s normal Sport Shutter login cookie with every API call. There are no tokens to issue, no passwords to handle and no cross-site permissions to configure.

  • Whose data it is comes from the session, never from the request. The API reads req.user.id from Sport Shutter’s own middleware, so a page can only ever read or change the signed-in person’s settings.
  • Saves can’t be forged from another site. Every change needs the X-ShutterLink: 1 header, which browsers won’t let another site add. Keep session cookies SameSite=Lax as well.
  • Everything sent is checked. Shape, sizes and links in the settings; type and size of photos; length and format of enquiries.
  • Visitors only read. The public call is read-only and strips private fields. Enquiries are the only public write, with a bot trap and a rate-limit hook.
  • The pages escape everything they show, so text in settings can never become code on the page. A strict Content-Security-Policy on /shutterlink/ adds a second layer.
  • Revisions stop lost changes. If the same settings are saved from two places, the second save gets 409 and the photographer chooses which to keep.
Nothing new to secure. ShutterLink adds no login, no tokens and no storage. The attack surface is seven endpoints behind Sport Shutter’s existing session, all in one reviewable file.

Every photographer gets sportshutter.com/@name, the address they put in their Instagram bio.

  • Chosen, not random. The first save claims a name made from theirs (grantwalker), adding a number if it’s taken. They can change it under Profile.
  • Rules. 3 to 30 characters: lowercase letters, numbers, dots, hyphens and underscores, starting and ending with a letter or number. Words like admin, api, settings and shop are reserved.
  • Renames never break links. The old name keeps working and sends visitors to the new one, so links already shared on Instagram stay good.
  • Behind the name is the user ID. Everything is filed under the permanent Sport Shutter user ID; the name is just a label pointing to it.

9. Hosting and releases

The pages are static files. Today they’re at shutterlink.gwstudio.com.au; they can stay there, move to any static host, or be served by Sport Shutter itself. A proxy rule makes them part of sportshutter.com:

nginx
location = /shutterlink { return 301 /shutterlink/; }

location /shutterlink/ {
    proxy_pass https://shutterlink.gwstudio.com.au/;
    proxy_set_header Host shutterlink.gwstudio.com.au;
    proxy_ssl_server_name on;
}

# Personal links: /@name serves the page, which reads the name from the address.
location ~ ^/@[a-z0-9._-]+/?$ {
    proxy_pass https://shutterlink.gwstudio.com.au/index.html;
    proxy_set_header Host shutterlink.gwstudio.com.au;
    proxy_ssl_server_name on;
}

Settings for Cloudflare, Vercel and Netlify are in DEPLOY.md. On sportshutter.com the pages switch to the real API automatically.

Speed

A visitor’s page is static files plus one small cached API call. Cache the public call at the CDN for a minute and clear it on the settings.saved event, and changes still show within seconds.

Independent releases

Sport Shutter deploys the API once. After that the ShutterLink team ships the pages on its own schedule, and no change to them needs a Sport Shutter release unless the API itself changes. The settings version number keeps the two in step.

10. Events

The API announces what happens through the onEvent hook. Sport Shutter decides what each one does.

EventCarriesSuggested use
settings.saveduserId, handle, revisionClear the CDN cache for that page
handle.changeduserId, from, toClear both names; update links Sport Shutter shows elsewhere
enquiry.receiveduserId, handle, enquiryIdNotify the photographer in the app and by email

11. Try it

The simulator runs server/shutterlink-api.js in the browser against a pretend database. It has two views.

  • Code flow. Pick one of 12 calls and press Run. It steps through the page code that makes the call, the request, the login check, the lines of shutterlink-api.js that decide the result, the database calls and what changed, the events, the response, and what the person sees. Edit the input and run it again.
  • Live pages. The real settings page and public page connected to the same pretend server, with every request in a log. The steps below use this view.
  1. Change your name in the settings.Watch the PUT appear in Requests and the visitor’s page update a moment later.
  2. Switch to Mia Chen.The settings reload with her page: each account only sees its own.
  3. Sign out.The settings ask you to sign in, and the gear disappears from the public page.
  4. Turn the server off, then edit.Changes are kept and save on their own when it comes back.
  5. Press “Save from another device”, then edit.The settings ask which version to keep.
  6. Send an enquiry from the visitor’s page.It arrives in the Inbox tab; the photographer’s email never reaches the page.
  7. Open “Try the API”.Send any call yourself, including a bad one, to see the checks.

12. Rollout

  1. Staff only.Deploy the API behind a feature flag. The Sport Shutter team makes their own pages and tries to break them.
  2. Invited photographers.Twenty active photographers put their link in their bio. Watch visits, print sales and enquiries from link pages.
  3. Everyone.“Create your link” in the dashboard, with the two-step setup.

How we’ll know it’s working

  • Photographers with a page, and how many put it in their bio
  • Visits arriving from Instagram
  • Print orders and enquiries started from link pages
  • New sign-ups from “Powered by Sport Shutter”

13. Questions

Does this touch our login system?

No. It reads the signed-in user that your existing middleware already sets. There’s no new login, token or password handling.

Why not build the pages inside the main app?

You can, later. Keeping them separate lets the ShutterLink team iterate on design without Sport Shutter releases. The API is the same either way, and the pages are plain files Sport Shutter can take over at any time.

Why the same domain instead of a subdomain?

On sportshutter.com the browser sends the existing login cookie automatically. A subdomain would need cookie, cross-origin and token changes for no benefit.

What happens to the shop and checkout?

Prints on the page are Sport Shutter products, and checkout hands over to the existing Sport Shutter checkout with the product IDs. Orders and payments never leave Sport Shutter.

What if a photographer’s settings get large or strange?

The server caps the size, checks every link, and rejects embedded photos. The pages are built to cope with missing or extra fields.

How do we test our side?

Run node server/test.js for the API, then point the pages at a staging server with ?backend=live. The simulator shows the exact requests and responses to expect.

ShutterLink for Sport Shutter · design brief and build guide. Code: server/shutterlink-api.js, server/memory-store.js, server/test.js, assets/data.js.