> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/public-website/docs/archive-docs_public-website/architecture.md).

# Public Website Architecture

`public-website/` is a package-local static Astro application. It belongs to the root npm workspace, but it is intentionally separate from the runtime web cockpit in `apps/web` and the synthetic public demo in `public-demo`.

## Runtime Shape

```
public-website/
|-- astro.config.mjs
|-- package.json
|-- public/
|   |-- favicon.svg
|   |-- robots.txt
|   |-- site.webmanifest
|   `-- press/
|-- src/
|   |-- assets/
|   |-- components/
|   |-- content/
|   |-- data/
|   |-- layouts/
|   |-- lib/
|   |-- pages/
|   `-- styles/
`-- docs_public-website/
```

Static output is generated into:

```
public-website/dist/
```

There is no server adapter, no server-rendered route, no runtime API route, no hosted form, no analytics runtime, and no CMS integration in the first-release site.

## Astro Configuration

`astro.config.mjs` defines:

* `site: "https://faction-os.com"`
* `output: "static"`
* integrations: `@astrojs/mdx` and `@astrojs/sitemap`

RSS is implemented as `src/pages/rss.xml.js` through `@astrojs/rss`. Image optimization uses Astro assets plus `sharp`.

## Package Dependencies

`public-website/package.json` owns website dependencies:

| Dependency         | Purpose                                            |
| ------------------ | -------------------------------------------------- |
| `astro`            | Static site generator and Astro component runtime. |
| `@astrojs/mdx`     | MDX support for publishing collections.            |
| `@astrojs/rss`     | RSS feed generation.                               |
| `@astrojs/sitemap` | Sitemap output.                                    |
| `sharp`            | Astro image processing.                            |
| `typescript`       | Type validation.                                   |
| `vite`             | Astro build dependency.                            |

The package is private and named `@factionos/public-website`.

## Data Flow

```
src/data/site.ts
  -> route contract, metadata defaults, external destinations, copy guardrails
  -> navigation data
  -> layouts, pages, SEO component, checker expectations

src/data/*.ts
  -> page-specific copy and structured content
  -> Astro page routes and marketing components

src/content.config.ts + src/content/{blog,news}
  -> typed content collections
  -> blog/news index routes, detail routes, RSS feed, related posts

src/lib/media.ts + src/assets
  -> typed local media registry
  -> OptimizedMedia.astro
  -> visible page media and metadata fallback assets
```

## Source Of Truth By Concern

| Concern                                  | Primary file                                        |
| ---------------------------------------- | --------------------------------------------------- |
| Site identity and canonical origin       | `src/data/site.ts`                                  |
| Fixed public routes                      | `src/data/site.ts`                                  |
| Demo/docs destinations                   | `src/data/site.ts`                                  |
| Contact mailboxes and mailto links       | `src/data/site.ts`                                  |
| Copy guardrails and no-claim policy      | `src/data/site.ts`                                  |
| Primary, footer, mobile nav              | `src/data/navigation.ts`                            |
| Homepage copy and samples                | `src/data/homepage.ts`                              |
| Product page copy                        | `src/data/product.ts`                               |
| Feature matrix and how-it-works pipeline | `src/data/features.ts`                              |
| Use-case hub and role pages              | `src/data/use-cases.ts`                             |
| Security page content                    | `src/data/security.ts`                              |
| Investors, about, contact, press         | `src/data/company.ts`                               |
| Roadmap                                  | `src/data/roadmap.ts`                               |
| FAQ and FAQ structured data              | `src/data/faq.ts`                                   |
| Blog/news schemas                        | `src/content.config.ts`                             |
| Publishing helper behavior               | `src/lib/content.ts`                                |
| Media provenance and image defaults      | `src/lib/media.ts`                                  |
| Metadata resolution                      | `src/lib/metadata.ts`                               |
| Built-site validation                    | `../../scripts/check-public-website-links.mjs`      |
| Deploy workflow                          | `../../.github/workflows/public-website-deploy.yml` |

## Layout And Component Boundaries

Layouts:

* `src/layouts/BaseLayout.astro`: document shell, global CSS import, SEO hook, body marker `data-static-output="true"`.
* `src/layouts/ContentLayout.astro`: reusable content page layout.
* `src/layouts/LegalLayout.astro`: legal/policy layout with pre-review state.
* `src/layouts/PostLayout.astro`: blog/news article layout with article metadata and related/neighbor posts.

Navigation:

* `Header.astro`, `MobileNavigation.astro`, `Footer.astro`, and `SkipLink.astro` consume route data rather than hard-coding destinations.

System primitives:

* `ButtonLink.astro`
* `Badge.astro`
* `Panel.astro`
* `MetricStrip.astro`
* `Section.astro`

Marketing and content components remain static and data-driven. Do not add client runtime behavior unless the behavior is required and documented in this directory.

## Publishing Architecture

Two content collections exist:

* `blog`: product thinking, architecture explainers, field notes.
* `news`: releases, changelog items, demo updates, company updates.

Production output excludes drafts through `src/lib/content.ts`. `includeDrafts` defaults to Astro dev mode only. The built-site checker validates draft exclusion in routes, RSS, and sitemap.

## Metadata Architecture

Every route receives metadata through `BaseLayout` and `Seo.astro`.

Metadata includes:

* `<title>`
* description
* robots
* canonical URL
* favicon
* manifest
* RSS alternate link
* Open Graph tags
* Twitter card tags
* JSON-LD structured data where applicable

Legal routes can set noindex/no-follow policy through `LegalLayout`.

## Media Architecture

Page media is imported through Astro from `src/assets/` and described in `src/lib/media.ts`. Each media entry records:

* key
* source and website path
* dimensions
* source byte size
* SHA-256
* release status
* intended use
* alt text
* responsive widths
* loading priority
* quality
* reduced-motion fallback where needed

`public/press/` is policy-only for the first launch. Do not add downloads there without updating [Media Assets](/faction-os-docs/public-website/docs/archive-docs_public-website/media-assets.md).

## Deployment Architecture

The deploy target is Cloudflare Pages static output.

Workflow:

```
push/manual dispatch
  -> npm ci
  -> public website typecheck
  -> public website build
  -> built-site checker
  -> credential-safe Pages deploy
  -> bounded HTTPS homepage smoke, only if deploy ran
```

The main website must not reuse the public demo Pages project, demo URL variable, or `public-demo/` artifact path.

## Static Privacy Boundary

The launch website is static presentation. Built output is expected to have:

* no analytics or tracker snippets
* no hosted forms
* no cookie writes
* no local/session storage writes
* no beacon calls
* no runtime `fetch`
* no `WebSocket`
* no `EventSource`

The deterministic checker enforces this on built output.

## When Architecture Changes

Update these docs when any of the following change:

* new route or removed route
* new approved external destination
* new content collection
* new media category or pass-through press file
* server adapter or runtime API
* analytics, forms, CMS, auth, hosted identity, hosted storage, search, or personalization
* deploy project name, smoke URL, or workflow behavior


---

# 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://faction-os.gitbook.io/faction-os-docs/public-website/docs/archive-docs_public-website/architecture.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.