How we built Arivu (and where it lives)

What we were trying to do

A read-only internal knowledge base: markdown in git, no CMS, fast pages, access limited to our Google workspace. No comments and no in-browser editing in v1. Ship markdown and read it in the browser.

The app is Astro. It turns markdown and layouts into static HTML, CSS, and JS. Hosting is S3 plus CloudFront, not an app server we run 24/7.

Staging

URL: https://arivu-staging.cybosapiens.com

CloudFront sits in front of the bucket. CI runs astro build, uploads dist/ to S3, then invalidates the cache so new HTML shows up quickly. Ordinary static-site-on-AWS setup.

Where the markdown lives

Everything you read as an article comes from:

knowledge_docs/
  <category>/        ← top-level folder = sidebar section
    *.md             ← one file = one page; nested folders = nested URLs

Routing rules:

Each doc is a .md under knowledge_docs/.
Frontmatter category must match the top-level folder (web, backend, etc.). Astro uses it for URLs and the sidebar.
Nested dirs become nested paths, e.g. backend/devops/deploy-pipeline.md → /backend/devops/deploy-pipeline.

Git is the source of truth. If a file is not under knowledge_docs/, the site does not list it.

Repo layout (high level)

arivu/
  knowledge_docs/     ← content
  src/
    pages/            ← routes: index, category lists, [...slug]
    layouts/          ← BaseLayout, DocLayout
    components/       ← Sidebar, PostList, etc.
    lib/              ← auth, downloads, CSP, markdown export
    styles/           ← global.css
  public/             ← favicon, scripts

dist/ is build output (gitignored). Deploy publishes dist/, not the whole repo tree.

SSO

Google SSO goes through Keystone, same pattern as our other internal web apps.

Only @asymmetriclabs.ai accounts are allowed in the Arivu UI (client-side check on /auth/me); Keystone may enforce additional rules in your deployment.
After OAuth, the browser keeps session cookies; pages use GET /av1/auth/me (and refresh) before showing protected content.

Static files come from S3/CloudFront. Session and tokens are Keystone. Markdown is never sent through Keystone; only auth is.

Next steps

Keep scope small (e.g. search later if we need it).
Optional: automate a zip of knowledge_docs/ for offline or tooling. Presigned download is documented under Backend → Arivu on Keystone, S3, and CloudFront.

DevOps quick reference

Piece	Role
GitHub Actions	Build Astro, upload `dist/` to S3
S3	Object store for the static site
CloudFront	CDN, TLS, `arivu-staging.cybosapiens.com`
Keystone	OAuth, JWT, presigned URL for the optional zip

Debugging: stale HTML usually means CDN/cache or deploy; login loops usually mean CORS, env, or cookies on the API side.