> For the complete documentation index, see [llms.txt](https://summerain-1.gitbook.io/summerain/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://summerain-1.gitbook.io/summerain/archived-design-records/frontend-architecture/05-build-and-deploy.md).

# 05 - Build and Deployment

> \[!WARNING] **Archived design record.** This page predates the completed V2 frontend and may contain obsolete versions, paths, or implementation status.

> Part of: [Frontend Architecture Design (Index)](/summerain/archived-design-records/frontend-architecture.md)

## Build

`vite build` -> `build.outDir: '../backend/web'`, `build.emptyOutDir: true`, and `base: '/'`.

> **`base` must be `'/'`, not the relative value `'./'`:** BrowserRouter uses HTML5 history routing. When a deep link such as `/images/123` is refreshed, the backend `NoRoute` handler falls back to `index.html`, and the browser resolves asset paths against the **current document URL**. With a relative base of `./`, `./assets/index.js` would resolve to `/images/assets/index.js`, hit the HTML fallback, and fail to load as a script. Vite's official documentation also warns that a relative base is incompatible with history-route refreshes. This frontend is deployed at the **domain root** (Go serves it from `./web/` on the same origin), so `base: '/'` is correct. A future subpath deployment would require changing both `base` and React Router's `basename` (not needed now).

The production build enables `vite-plugin-sri3` to inject SHA512 `integrity` attributes and emits `assets.manifest.json` (one `{ version, integrity }` entry per artifact; see [07 Production Standards](/summerain/archived-design-records/frontend-architecture/07-production-standards.md)).

## Production Deployment

A single Go process serves `backend/web/`, `/api`, and `/i` on the same origin, so cookies are naturally same-origin.

## Development Workflow

Vite runs on `:5173` over HTTPS. `server.proxy` forwards `/api` and `/i` to Go at `http://localhost:8080`, preserving same-origin cookies during development.

**Proxy requirements for `__Host-` cookies** (otherwise the browser rejects them and the session cannot persist):

* Set `changeOrigin: true`, and **do not** set `cookieDomainRewrite` or `cookiePathRewrite` (`__Host-` requires no Domain attribute and Path=/; either rewrite would violate the prefix rules).
* Forward the response `Set-Cookie` header unchanged. HTTPS on :5173 satisfies the `Secure` flag; although upstream Go uses HTTP, `c.SetCookie` still emits `Secure`, and the browser accepts it through the HTTPS-facing proxy.
* Cookies are stored for `localhost:5173` (the proxy origin) and are then sent automatically on `/api` and `/i` requests.
* This works in conjunction with the HTTPS prerequisite below.

## ⚠️ HTTPS Is Required (Hard Development Prerequisite)

Cookies with the `__Host-` prefix require `Secure` and HTTPS. On local HTTP, the browser rejects `__Host-session_token`, so the login session cannot persist. The development environment **must** enable HTTPS for Vite (with `@vitejs/plugin-basic-ssl` or mkcert); otherwise, login integration cannot work correctly.

***

<- [04 Theme and UI](/summerain/archived-design-records/frontend-architecture/04-theme-and-ui.md) · [Index](/summerain/archived-design-records/frontend-architecture.md) · Next: [06 Testing Strategy](/summerain/archived-design-records/frontend-architecture/06-testing.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://summerain-1.gitbook.io/summerain/archived-design-records/frontend-architecture/05-build-and-deploy.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.