1. What Marley is

Marley is a production-grade Next.js site template that proves its own flexibility by wearing different costumes. The same codebase is styled for multiple fictional businesses from public domain literature — each with a distinct voice, palette, and copy — without touching routing, components, or infrastructure.

The base codebase was derived from the Medhavy adaptive learning platform (Medhavy LLC, Nik Bear Brown and Srinivas Sridhar). All Medhavy branding has been replaced per brand instance. The infrastructure — routing, admin, database schema, API contracts — is shared and unchanged across instances.

Current brand instances

All source works are public domain. The brands as implemented — copy, design, codebase — are not.

2. Tech stack

3. Multi-brand theming system

The theming system is the core architectural claim of the Marley template. Changing a brand requires editing three files. No component changes. No routing changes. The entire site repaints.

The three files that must stay in sync

Palette variable roles (mandatory conventions)

4. Site structure and routes

Public routes

• /Home — five sections: hero, services, who we serve, CTA, contact
• /toolsTools directory — card grid merging filesystem artifacts and DB link tools
• /tools/[slug]Artifact embed page — full-viewport iframe with title bar
• /devDev docs browser — searchable card grid, filesystem-driven
• /dev/[slug]Single dev doc — full-viewport iframe
• /blogBlog feed — cover thumbnails, search bar, published posts newest first
• /blog/[slug]Blog post — cover hero, prose content, og:image, prev/next nav
• /aboutFirm/person page — prose format, founders, contact
• /privacyPrivacy policy
• /privacy/cookiesCookie policy — dedicated page
• /terms-of-serviceTerms of service
• /substackNewsletter hub — card grid of all sections
• /substack/[section]Section page — article list, follow CTA
• /substack/[section]/[slug]Full article — attribution banner, prose, subscribe CTA

Admin routes (protected)

• /admin/loginPassword form — POSTs to /api/admin/login
• /admin/dashboardOverview — tabbed nav to all admin sections
• /admin/dashboard/blogPost list — tag filter, bulk delete, import/export
• /admin/dashboard/blog/newNew post editor
• /admin/dashboard/blog/[id]/editEdit existing post
• /admin/dashboard/blog/importImport — Substack ZIP or blog export ZIP
• /admin/dashboard/toolsTools manager — link and artifact types
• /admin/dashboard/devDev docs list — filesystem browser with sync button
• /admin/dashboard/substackSubstack section manager — create sections, import ZIPs

5. Content systems

Blog system

The blog system uses Neon PostgreSQL for post storage, Tiptap for authoring, and Vercel Blob for image storage. Posts are database-driven; the admin editor produces clean HTML stored in the content column.

• WYSIWYG editor: bold, italic, headings, lists, blockquotes, code blocks, images, YouTube embeds, D3 viz placeholders
• Cover image upload via drag/drop to Vercel Blob
• Tags stored as PostgreSQL TEXT[] array — filterable in both admin and public views
• Draft/publish workflow with published_at timestamp
• Auto-generated slug from title (editable), auto-generated excerpt (first 200 chars)
• Export as ZIP (posts.json + individual HTML files) — enables cross-instance transfer
• Import from Substack export ZIP or blog export ZIP
• D3 data visualisations hydrated client-side via BlogVizHydrator and the viz registry

1. Create lib/viz/[name].ts exporting default (el: HTMLElement) => void
2. Add an entry to lib/viz/registry.ts mapping the name to a lazy import
3. Insert a data-viz="[name]" placeholder via the editor toolbar

Tools directory

Tools are served from two sources merged at render time. Artifact tools live as HTML files in public/artifacts/ — filesystem is the source of truth, no database entry needed. Link tools are database-driven, managed via the admin UI.

Dev docs browser

All HTML files in public/dev/ are automatically surfaced on /dev. No database, no sync required. The lib/html-meta.ts utility (scanHtmlDir()) reads <title>, <meta name="description">, and <meta name="keywords"> tags from every file and returns them as HtmlDocMeta[].

Substack importer

The Substack import system ingests Substack export ZIPs and surfaces articles under /substack/[section]/[slug]. Articles are stored in Neon with attribution preserved.

1. Export from Substack (Settings → Exports → Create new export)
2. Create a section in admin dashboard (title, slug, Substack URL, description)
3. Upload the ZIP to that section — parser reads posts.csv + HTML files
4. Articles upserted by slug — re-import is safe, updates existing records

6. Database schema

Four tables in Neon PostgreSQL. All have row-level security enabled. Public read policies are narrowly scoped — blog posts require published = true.

-- Tools
CREATE TABLE IF NOT EXISTS tools (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL,
  slug TEXT UNIQUE NOT NULL,
  description TEXT,
  tool_type TEXT DEFAULT 'link',       -- 'link' | 'artifact'
  claude_url TEXT,                      -- external URL (link tools) or fallback
  chatgpt_url TEXT,                     -- optional ChatGPT URL
  artifact_id TEXT,                     -- Claude artifact UUID
  artifact_embed_code TEXT,             -- raw iframe embed (overrides artifact_id)
  tags TEXT[],                          -- category tags
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);
ALTER TABLE tools ENABLE ROW LEVEL SECURITY;
CREATE POLICY "public_read_tools" ON tools FOR SELECT USING (true);
CREATE POLICY "service_role_tools" ON tools FOR ALL USING (true) WITH CHECK (true);

-- Blog posts
CREATE TABLE IF NOT EXISTS blog_posts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title TEXT NOT NULL,
  subtitle TEXT,
  slug TEXT NOT NULL UNIQUE,
  byline TEXT,
  cover_image TEXT,
  content TEXT NOT NULL,               -- clean HTML from Tiptap
  excerpt TEXT,                        -- auto-generated, first 200 chars
  published BOOLEAN DEFAULT false,
  published_at TIMESTAMPTZ,
  tags TEXT[] DEFAULT '{}',
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);
ALTER TABLE blog_posts ENABLE ROW LEVEL SECURITY;
CREATE POLICY "public_read_published_posts" ON blog_posts
  FOR SELECT USING (published = true);
CREATE POLICY "service_role_posts" ON blog_posts
  FOR ALL USING (true) WITH CHECK (true);

-- Substack sections
CREATE TABLE IF NOT EXISTS substack_sections (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  slug TEXT NOT NULL UNIQUE,
  title TEXT NOT NULL,
  description TEXT,
  substack_url TEXT NOT NULL,
  article_count INTEGER DEFAULT 0,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);
ALTER TABLE substack_sections ENABLE ROW LEVEL SECURITY;
CREATE POLICY "public_read_sections" ON substack_sections FOR SELECT USING (true);
CREATE POLICY "service_role_sections" ON substack_sections
  FOR ALL USING (true) WITH CHECK (true);

-- Substack articles
CREATE TABLE IF NOT EXISTS substack_articles (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  section_id UUID NOT NULL REFERENCES substack_sections(id) ON DELETE CASCADE,
  slug TEXT NOT NULL,
  title TEXT NOT NULL,
  subtitle TEXT,
  excerpt TEXT,
  content TEXT,
  original_url TEXT,
  published_at TIMESTAMPTZ,
  display_date TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(section_id, slug)
);
ALTER TABLE substack_articles ENABLE ROW LEVEL SECURITY;
CREATE POLICY "public_read_articles" ON substack_articles FOR SELECT USING (true);
CREATE POLICY "service_role_articles" ON substack_articles
  FOR ALL USING (true) WITH CHECK (true);

Pending migrations (safe to re-run)

-- Run these in Neon SQL Editor if not already applied
ALTER TABLE blog_posts ADD COLUMN IF NOT EXISTS byline TEXT;
ALTER TABLE blog_posts ADD COLUMN IF NOT EXISTS tags TEXT[] DEFAULT '{}';
ALTER TABLE blog_posts ADD COLUMN IF NOT EXISTS cover_image TEXT;

7. Admin system

The admin dashboard is protected by middleware.ts, which redirects all /admin/dashboard/* routes to /admin/login if no valid admin_session cookie is present. Authentication is password-only — the password is set via the ADMIN_PASSWORD environment variable.

• Login: POST to /api/admin/login — validates against ADMIN_PASSWORD env var
• On success: sets admin_session httpOnly cookie, 7-day expiry
• All /api/admin/* routes check isAdmin() from lib/admin-auth.ts before proceeding
• Middleware protects dashboard pages; API routes protect data endpoints separately

Admin API routes

8. Environment variables

9. Persistent layout components

Header

Sticky, z-50, backdrop-blur. Logo (theme-aware SVG or text), five-item nav, social icon buttons, dark/light mode toggle. Mobile hamburger menu at the lg breakpoint. Do not add a sixth nav item without a deliberate information architecture decision — five is not arbitrary.

Footer

Four-column grid: firm info (name, address, contact), platform links, connect/social links, legal links. Bottom bar with copyright. Column headings and link text are brand-specific copy — the only footer content that changes between instances.

SEO infrastructure

• app/sitemap.ts — dynamic sitemap including all /blog/*, /tools/*, /substack/* routes from Neon. Falls back to static-only if DB is not configured.
• app/robots.ts — allows all crawlers, blocks /admin/ and /api/, points to /sitemap.xml.
• Blog posts include og:image and twitter:card meta tags.

10. Five proposed additions

These are structural proposals, not implementation tickets. Each one addresses a real gap in the current template. They are ordered by the ratio of effort to usefulness, not by complexity.