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.
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.
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.
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.
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.
- Copy one file into the server.
server/shutterlink-api.js. No dependencies; Node 18 or later. Runnode server/test.jsto check it (38 checks). - Add one table, and two small ones.Settings per photographer, old link names, and enquiries. SQL below.
- Write the store: five functions against that table.A PostgreSQL version is below;
server/memory-store.jsshows the exact behaviour. - Mount it after the session middleware.Three lines in Express. It answers only
/api/shutterlink/*and/api/public/pages/*. - Route the pages through a proxy.
/shutterlink/*and/@*go to ShutterLink’s hosting. See Hosting. - Add a button to the dashboard.“Edit my link page”, linking to
/shutterlink/settings.html.
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()
);// 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;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));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.
| Call | Who | What it does |
|---|---|---|
GET /api/shutterlink/me | Signed in | Who is signed in and their link name |
GET /api/shutterlink/settings | Signed in | Their settings file and revision |
PUT /api/shutterlink/settings | Signed in | Save the whole settings file |
PUT /api/shutterlink/handle | Signed in | Change their link name |
POST /api/shutterlink/images | Signed in | Upload a photo, get its address |
GET /api/public/pages/:handle | Anyone | A page’s public settings, cacheable |
POST /api/public/pages/:handle/enquiries | Anyone | Send an enquiry to the photographer |
/api/shutterlink/meSigned in200 { userId, name, handle, suggestedHandle }. handle is null until the first save; suggestedHandle is a free name based on theirs.401 signed_out: the pages show a sign-in screen./api/shutterlink/settingsSigned in200 { settings, revision, updatedAt, handle }. settings is null the first time; the pages then start from defaults with the person’s name./api/shutterlink/settingsSigned in{ settings, revision } with header X-ShutterLink: 1. revision is the one they loaded.200 { revision, updatedAt, handle }. The first save also claims a link name.409 conflict saved elsewhere since loading (the page asks which to keep) · 422 invalid_settings with errors: [{ path, message }] · 403 csrf · 429/api/shutterlink/handleSigned in{ handle } with X-ShutterLink: 1200 { handle }. The old name becomes a redirect.409 taken · 422 invalid_handle (rules in Personal links)/api/shutterlink/imagesSigned inContent-Type: image/jpeg (or png, webp), with X-ShutterLink: 1. The pages shrink photos before sending.201 { url }, which the settings then refer to.413 too_large (over 8 MB) · 415 unsupported_type/api/public/pages/:handleAnyone200 { handle, settings, revision, updatedAt } with private fields removed. Cache-Control: public, max-age=60, stale-while-revalidate=600.301 { movedTo } an old name: the page follows it · 404 not_found/api/public/pages/:handle/enquiriesAnyone{ name, email, type, date, msg }202 { ok: true }. A hidden website field catches bots: if it’s filled in, the message is quietly dropped.422 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.
vmust be2. 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:orfile:addresses, and no embeddeddata: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.idfrom 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: 1header, which browsers won’t let another site add. Keep session cookiesSameSite=Laxas 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
409and the photographer chooses which to keep.
8. Personal links
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,settingsandshopare 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:
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.
| Event | Carries | Suggested use |
|---|---|---|
settings.saved | userId, handle, revision | Clear the CDN cache for that page |
handle.changed | userId, from, to | Clear both names; update links Sport Shutter shows elsewhere |
enquiry.received | userId, handle, enquiryId | Notify 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.jsthat 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.
- Change your name in the settings.Watch the
PUTappear in Requests and the visitor’s page update a moment later. - Switch to Mia Chen.The settings reload with her page: each account only sees its own.
- Sign out.The settings ask you to sign in, and the gear disappears from the public page.
- Turn the server off, then edit.Changes are kept and save on their own when it comes back.
- Press “Save from another device”, then edit.The settings ask which version to keep.
- Send an enquiry from the visitor’s page.It arrives in the Inbox tab; the photographer’s email never reaches the page.
- Open “Try the API”.Send any call yourself, including a bad one, to see the checks.
12. Rollout
- Staff only.Deploy the API behind a feature flag. The Sport Shutter team makes their own pages and tries to break them.
- Invited photographers.Twenty active photographers put their link in their bio. Watch visits, print sales and enquiries from link pages.
- 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.