🧭 Product & Domain Overview

📋 Summary

Midshift is a web application that runs the production side of retail advertising campaigns: it takes a campaign from brief and media plan through copywriting, artwork, video edits, tracking links and approvals to a final "handover" grid that a client, media buyer or archive team can take away. Its central idea is that every advert ("ad unit") has one agreed name, and that name is used to join the copywriter's Word document, the designer's exported files and the app's own records, so files and copy land in the right place without manual sorting. The code shows a clear, opinionated product with a well-defined audience (an in-house retail marketing team plus its agencies and suppliers) and several genuinely distinctive features, notably a forgiving copy-deck parser and a shared filename-to-advert matcher. It is built to be installed once per client (one database and one hosting project each), not as a shared multi-customer service, and it has no translation layer: the interface is English only. Market position, pricing, customers and revenue cannot be judged from the repository.

🎯 Rating

🟢 ●●●●○ 4 / 5 — Good (Green). Purpose, domain model and user journeys are coherent and consistently expressed in code, schema, tests and UI copy; the score is held back from 5 by scope sprawl (two navigation shells, orphaned and removed features still present on disk, four campaign "kinds") and small schema/type mismatches in the role model.

🔍 Findings

1. Purpose and problems solved

The README's own framing is "the record that makes a sign-off mean something" and "nothing is stored as 'ready', 'approved' or 'live' that the artefacts don't prove" ([Observed] README.md:3-12). ARCHITECTURE.md states the invariant "Status is derived, never stored" and points to src/lib/campaign-derive.ts, src/lib/final-load.ts and src/lib/for-you.ts ([Observed] ARCHITECTURE.md:25-33). Those files exist and implement derivation on read.

2. Business domain and target users

Domain [Observed]: retail marketing campaign production across paid social, display, programmatic, ride-hailing and out-of-home. The channel enum is meta, tiktok, google, pinterest, triplelift, uber, ooh (supabase/baseline.sql:60). Campaigns have a kind of season | concept | rollout | ooh (supabase/baseline.sql:2091): a season groups jobs, a concept job holds the big idea and master video, rollouts adapt it to channels, and OOH jobs manage billboard/LED sites.

Geography [Inferred]: deployment and compliance documents analyse South African data-protection law (POPIA) and Vercel's Cape Town region (docs/NEW_DEPLOYMENT.md:110-127; design/COMPLIANCE.md:12-14), indicating a South African launch market. Not confirmable from code.

Users and roles [Observed]:

The role model is coherent in intent (a tier says whether you may write; a discipline says which part), but the global tier is inconsistent between code and schema: the app accepts reviewer as a valid role in the invite and user-edit routes (src/app/api/admin/invite/route.ts:7, src/app/api/admin/users/[id]/route.ts:10) and gates several screens on it (e.g. units-page.tsx:172), but no migration adds reviewer to the user_role enum (searched all alter type ... add value statements). [Inferred] Assigning the reviewer role would be rejected by Postgres, so the "reviewer" experience the UI codes for is likely unreachable. The legacy enum values left by migrations 031–034 are also still present.

3. Differentiators evident from the implementation

Competitive differentiation versus established tools (e.g. creative-ops, DAM or ad-ops platforms) is [Unavailable] — requires market analysis and customer interviews.

4. Strategic objectives implied by the code

5. Core user journeys

Navigation: signed-in users are redirected from / to the workspace shell (/workspace); the older "classic" dashboard survives at /?classic=1 and old /campaign/[id]/… routes 308-redirect into the workspace (next.config.ts:23-33).

The help page's section titles mirror this flow exactly ("How a job flows", "One name for everything", "The media plan makes the ad units", "The copy deck", "Files match themselves", "Video edits and the supplier link", "Who does what", "UTMs and the Final grid", "Out-of-home") ([Observed] src/app/(app)/workspace/help/help-view.tsx), which is good evidence that the product's mental model is shared between code and user-facing copy.

6. Coherence and scope observations

7. Market positioning and commercial facts

🧾 Evidence

• Files read: README.md, ARCHITECTURE.md (§1–3, 5, 8–9), CLAUDE.md, docs/NEW_DEPLOYMENT.md, docs/README.md, src/app/qa/fixtures.ts:1-30, src/lib/ask-intent.ts:1-40, src/lib/discipline.ts:19-32, src/lib/config.ts, src/lib/branding.ts, src/app/(app)/workspace/ask-sheet.tsx, src/app/(app)/workspace/ws-new-campaign.tsx, next.config.ts:23-33, supabase/baseline.sql (enums, tables).
• find src/app -name page.tsx | grep -v '/qa/'→ 39 product pages (including the root/and the unreachable classic pages); the/qa/*` harness adds 24 more.
• find src/app/api -name route.ts → 83 route files.
• grep -rln "i18n\|next-intl\|useTranslation" src and package.json → no i18n library.
• grep -rhoE "toLocale[A-Za-z]*\('[^']*'" src → en-US ×1, en-GB ×1, en-AU ×1 (comment).
• grep -n "create type user_role" -A3 supabase/baseline.sql → enum without reviewer; grep -rn "add value" supabase/migrations → no migration adds it.
• grep -oiE 'create table …' supabase/baseline.sql | sort -u | wc -l → 44 tables.
• grep -rn "\.range(" src | grep -v qa/ | wc -l → 1; .limit( → 16.
• Shared facts from the brief: test coverage figures, cloc, single commit.

⚠️ Risks

✅ Recommendations