frontend-helper/README.md

# Minnect Feed Browser

A small web client for the Minnect expert home feed. You run it on your own
machine, sign in with **your own** Minnect email and password, and then read and
write the feed as yourself — read posts, like, comment, and publish text, image,
and video posts.

> **Unofficial.** This is an independent, community-built client. It is not
> affiliated with, endorsed by, or supported by Minnect or Valuetainment. It
> uses your own Minnect account credentials, which you provide, to talk to
> Minnect's API on your behalf. Use it at your own discretion and in line with
> Minnect's terms of service.

## What it does

- **Sign in with your own Minnect account.** Your tokens are kept on the local
  server behind an httpOnly session cookie — they never reach the browser, the
  JavaScript bundle, a URL, or a log line.
- **One home feed, newest first,** with your own posts interleaved in their
  correct time order (not all bunched at the top), infinite scroll, and a gentle
  ~45s poll that offers new posts without yanking the page.
- **Likes** — like and unlike, with the count kept in sync.
- **Comments** — read a post's comments and add your own.
- **Posts** — publish a public text post, or a post with one image or one video.
  Uploads go through the local server, so your feed token never touches the
  browser or the storage bucket.
- **Delete** your own posts (and only your own).
- Responsive — works on a phone-width window and on the desktop.

## How it works

```
your browser  --cookie session-->  this app (localhost)  --Bearer token-->  Minnect
```

The browser only ever talks to this app. This app talks to Minnect server-side.
That keeps your Minnect tokens off the browser entirely and avoids cross-origin
restrictions. See `CLAUDE.md` and `docs/` (if present) for the design notes.

## Design system

The redesign (obsidian, crimson, no gold) is specified in
[`docs/minnect-feed-redesign.spec.md`](docs/minnect-feed-redesign.spec.md). The
styling decisions are in
[`docs/adr/0001-redesign-styling-approach.md`](docs/adr/0001-redesign-styling-approach.md).
The handoff for the redesign is [`docs/handoff-redesign.md`](docs/handoff-redesign.md).

- **Themes.** Dark is the default; light is a toggle. The choice is stored in
  `localStorage` and applied by a small script in `src/app/layout.tsx` before
  first paint (`src/lib/theme.ts`), so there is no flash. `src/lib/use-theme.ts`
  is the hook the toggles use.
- **Tokens.** All colors are CSS custom properties in `src/app/globals.css`, one
  set for dark and one for light. `--accent-text` is the readable crimson for
  small text (4.5:1). Components use tokens only, never raw colors.
- **Stylesheets.** One file per component area in `src/styles/` (`buttons.css`,
  `feed.css`, `post.css`, `mobile.css` and so on), loaded from `globals.css`.
- **Buttons.** Five styles plus a small icon button, all in
  `src/components/Buttons.tsx`: Flip (the composer Post button), Grow (the
  "new posts" pill), Sweep (outline actions: Try again, Cancel, expert search
  chips), Depth (the Discover sheet rows), Sparkle (Sign in and the mobile dock
  new-post button) and IconButton (refresh, comment send, delete confirm). Disabled buttons stay at full opacity.
- **Avatars.** `HexAvatar` (`src/components/HexAvatar.tsx`) is used for every
  avatar: photo, or initials on a gradient, in a hexagon.
- **Breakpoints.** Container queries on the app root: 1181 and up (three
  columns), 1001 to 1180 (narrower columns), 761 to 1000 (tablet), 760 and below
  (full-screen snap feed with a bottom dock).
- **Dev previews.** `/dev/feed` (fixture feed, no login) and `/dev/buttons` (every
  button style in both themes). Both return 404 in production builds.

## Requirements

- Node.js 20 or newer (built and tested on Node 22).
- A Minnect account (your own email and password).

## Install and run

You need **Node.js 20 or newer** (`node -v` to check) and your own Minnect
account.

**1. Get the code**

```bash
git clone <this-repo-url> minnect-feed-browser
cd minnect-feed-browser
```

**2. Install the dependencies**

```bash
npm install
```

**3. Start the app**

```bash
npm run dev
```

**4. Open it in your browser.** When it's ready, the terminal prints a local
link:

```
  ▲ Next.js 15.5.28
  - Local:        http://localhost:3000
```

👉 **Click that link — http://localhost:3000** — most terminals make it
clickable (Cmd-click on macOS, Ctrl-click on Windows/Linux). If it isn't
clickable, copy and paste it into your browser.

**5. Sign in** with your own Minnect email and password. That's it — you're in
the feed. (A wrong password just shows one generic message and signs no one in.)

To stop the app, press `Ctrl+C` in the terminal.

### Production-style run (optional)

To build once and run the optimized build instead of dev mode:

```bash
npm run build && npm start
```

Then open the same link: **http://localhost:3000**.

## Configuration

No configuration is required — the Minnect host URLs have sensible defaults. To
override them (for example to point at a different environment), copy
`.env.example` to `.env.local` (which is gitignored) and edit the values:

```bash
cp .env.example .env.local
```

| Variable            | Default                                  | What it is                                   |
| ------------------- | ---------------------------------------- | -------------------------------------------- |
| `PROFILES_BASE_URL` | `https://profiles.minnect.com`           | Sign-in, auth/me, refresh, revoke, feed token |
| `FEED_BASE_URL`     | `https://feed.sharedservices.vt.com`     | Home feed, posts, likes, comments            |

## Scripts

| Command           | What it does                      |
| ----------------- | --------------------------------- |
| `npm run dev`     | Start the dev server              |
| `npm run build`   | Production build                  |
| `npm start`       | Run the production build          |
| `npm test`        | Run the test suite (Vitest)       |
| `npm run lint`    | Lint                              |
| `npm run typecheck` | Type-check with `tsc`           |

## Limitations (by design — this is a simple, local tool)

- **Run it locally.** It is meant to run on your own machine over
  `http://localhost`, for one person at a time.
- **Sessions live in memory.** They are held in the running Node process, so
  restarting the server signs you out. That is fine for local use.
- **Not built for public or multi-instance hosting as-is.** The in-memory
  session store does not work across multiple server instances or serverless
  functions, and the session cookie is `Secure` (so a public deployment needs
  HTTPS). Hosting it for real would mean swapping the store in
  `src/lib/session-store.ts` for a shared one (e.g. Redis) and serving over TLS.
- **No admin features.** By design it only touches the regular user feed — no
  admin routes, no shared account, no ticketing, wallet, circles, or paid
  questions.

## Security notes

- Your credentials are sent only to your own local server, which exchanges them
  with Minnect and keeps the resulting tokens server-side. The browser receives
  only an opaque session id in an httpOnly cookie.
- A build of the frontend contains no tokens or passwords.
- Because it runs locally and holds your live session, treat the machine you run
  it on as you would any signed-in session.

## License

MIT — see [LICENSE](LICENSE).