A familiar city.
A React foundation.

Run the Next.js project

Install Node.js 20.9 or later. A maintained LTS version is recommended. Open a terminal in the folder containing package.json and run:

npm install
npm run dev

Open http://localhost:3000/ for the website and http://localhost:3000/admin/ for the workspace. The optional demo-entry page is /admin/login/; no password is required. Do not run the old HTML Python-server workflow against these source files.

Application dependencies are configured as Next.js 16.4.0 and React/React DOM 19.3.0. Dependencies are installed with npm; fonts load from Google Fonts. Internet access is needed for installation; retain the lockfile created by a successful install.

Application links work when served by Next.js or the static preview server.

Components, not embedded HTML

The application uses real TSX components, React state and Next navigation. There are no HTML-page iframes or legacy DOM-injection scripts. Styling is plain, editable CSS with design tokens, so there is no UI kit to learn.

src/
  app/                    App Router pages, layouts and metadata
  components/
    public/screens/       Individual public page layouts
    public/               Header, footer, heroes, cards and forms
    admin/                Workspace, editors, tables and settings
    ui/                   Shared SVG icons and UI elements
  context/                Browser-local shared demo store
  data/                   Typed seed content, images and schemas
  lib/                    Types, validation and export utilities
  styles/                 Retained CSS and React integration styles
public/                   Static images, documents and this guide
tests/                    Real-application Playwright tests
tools/                    Export, preview and image-download scripts

Change content without changing the design

Edit src/data/seed.json for initial content and branding. Use Admin > Portal settings for temporary changes in the current browser. Existing saved demo data takes precedence over an edited seed; export your work and reset the demo to reload the seed.

Raleway headings and Josefin Sans text are declared through the Google Fonts link in src/app/layout.tsx. No font files are included; system fallbacks apply when the font service is unreachable. Colors and spacing remain in src/styles/portal.css and src/styles/admin.css. React-specific additions are in react.css.

Public screen layouts have separate modules in src/components/public/screens/. Admin editor fields and table columns are in src/data/admin-schema.json. Page titles and descriptions live in route metadata, not in the browser-local settings form. Update those when changing the permanent brand.

Public forms and admin edits share local data

Submit a fictional resident request, copy its reference, open the admin Requests screen and change its status or public note. Track that reference on the public site to see the change. Create and publish a city story to show it in the newsroom; Draft hides it from the public list.

The collection screens support search, status filters, sorting, pagination, create/edit/delete and filtered CSV export. Contact messages and newsletter subscriptions save to their admin lists. Event details generate calendar files. The media library accepts JPEG, PNG and WebP uploads up to 1 MiB each; files are stored locally and can exhaust browser storage.

Settings includes JSON export, validated import and reset confirmation. Backups from the version-1 HTML edition use the same alderford.portal.v1 storage key. Data is separate for each browser origin, port, private window and device; use a backup to move it. Other tabs on the same origin can receive storage updates.

Sources, dimensions and local fallbacks

The eight demo photographs are free Pexels images, included in public/assets/images/ and cropped to the sizes below. To re-download the original crops, run the command below with -- --force. Replace all photos with your own city imagery before launch.

npm run images:download

Run this on a machine with network access, then rebuild. The script verifies JPEG dimensions, saves successful crops under public/assets/images/ and updates src/data/photos.json. Failed images remain remote references with local fallbacks. Use -- --force to refresh downloaded files.

Target crops: hero 1920 × 723, inner banner 1920 × 426, introduction 1280 × 960, and cards 1000 × 680. These are layout dimensions, not marketplace promotional-banner dimensions.

Photographs illustrate a fictional city. No endorsement is implied. Verify your template and image permissions before distribution; source credits do not establish a resale entitlement.

Node hosting or a static frontend export

npm run typecheck
npm run build
npm start

For Node hosting, use the production Next build, not the development server. A managed Next-compatible host can run the build and production service for you. No environment secrets are required by this demo.

npm run export
npm run preview

The optional export writes out/. Preview at http://127.0.0.1:4173/, then upload the contents of out/ to a static host that serves directory index.html files and supports a 404.html fallback. The project assumes a domain-root deployment. Subdirectory deployment needs coordinated asset and URL changes.

Static hosting does not add server persistence. Detail views use query-string IDs so newly created local records work without generating new build-time paths. When you add a real backend, review the export constraints again.

Page directory and legacy mapping

Use the new Next.js paths below. Old application .html URLs are not automatically rewritten. A native Next not-found page handles unknown routes in addition to the named error example.

Add a backend before collecting real data

Replace the browser store with authenticated server reads and mutations. Use separate public and staff data models, enforce server-side authorization, validate uploads and form submissions, implement safe request verification, add secure email delivery and subscription handling, and build an audit trail. A reference number alone is not a secure credential for private request access.

The chart history, contact details and all records are fictional. Real analytics, account security, database backups, email, spam controls, consent and retention workflows are not implemented. Read documentation/INTEGRATION.md in the source package for the integration checklist.

Quality checks

This edition passes npm run typecheck, npm run build and npm run export, and the included Playwright suite (43 tests) covering every route, the resident request flow from public form to admin to public tracker, publishing and deleting stories, branding persistence, mobile menus and the not-found page.

npx playwright install chromium
npm test

The tests start a local development server automatically. Set PLAYWRIGHT_BASE_URL to test an already-running build instead. Re-run the suite after customizing.