Overview
Purpose and Scope
OpenWiki is a hosted documentation generator for GitHub repositories. Its core promise is to turn a repository into a living, source-grounded wiki: users provide a repository, the system plans a docs-style outline, generates pages with citations, publishes a navigable wiki, supports chat over the indexed source context, and refreshes existing wikis as source repositories change. This page orients contributors and operators to the product surfaces visible in the repository root, the home page, and the package metadata before they dive into pipeline, storage, API, or component-specific pages.
Sources: README.md, package.json
The reader problem OpenWiki addresses is not simply markdown generation. Large repositories often have scattered source files, partial first-party documentation, and fast-changing implementation details. OpenWiki packages an opinionated workflow around that problem: it indexes public GitHub repositories, produces page-level evidence, and presents the result as a public documentation site rather than a one-off report. The README describes this as a Next.js app backed by an eve agent, which is important because the user-facing web app and the agent-driven indexing work are separate concerns that cooperate through storage, jobs, and generated artifacts.
Sources: README.md
Product Surfaces
The first product surface is the public home page. The Next.js route in app/page.tsx is statically configured with dynamic = "force-static" and revalidate = false, then renders RepositoryHome inside a Suspense boundary and appends OpenWikiFooter. That means the entry page is designed as a stable public landing surface, while the client component can still fetch fresher featured repository metadata after hydration. The home page also requests featured repository cards with a storage-configuration fallback, so a fresh or partially configured deployment can still render useful content rather than failing at the first page load.
Sources: app/page.tsx
The second surface is repository discovery and creation. RepositoryHome maintains a repository input string, validates whether it parses as a GitHub repository URL, and uses search behavior when the input looks like a query instead of a direct repository URL. The component debounces the search path with a browser timeout, calls /api/repositories/search?q=..., tracks loading, success, and error states, and displays messages such as no search results or inability to search GitHub. This puts the main user journey directly on the landing page: paste a GitHub URL, search by name, or follow a featured card.
Sources: app/components/repository-home.tsx
The third surface is the generated wiki itself. The README explains that a repository route such as /vercel/next.js is a valid way to open the app after deployment or local startup. That route convention is central to the product model: repository identity becomes part of the URL, and the wiki pages sit behind a stable owner/repository namespace. The same README list calls out docs-style navigation, official-docs-shaped outlines when first-party docs exist, featured wiki prerendering, and daily refresh scheduling, so the generated wiki is intended to behave like durable documentation rather than a temporary chat transcript.
Sources: README.md
The fourth surface is repository chat. The README states that OpenWiki includes repository chat using the same indexed source context. From an overview perspective, this matters because OpenWiki’s index is not only an input to generated markdown pages. It is also a reusable knowledge base for interactive Q&A. Contributors should therefore think of indexing outputs as shared product infrastructure: page generation, navigation, citations, refresh, and chat all depend on the same commitment to source-grounded repository understanding.
Sources: README.md
Relevant Source Files
README.md— Defines the product promise, deploy flow, local run commands, storage requirements, environment variables, and high-level feature list.package.json— Declares the runtime baseline, Next.js/eve/React dependencies, and primary development scripts used to build, run, and typecheck the application.app/page.tsx— Implements the root home route, fetches featured repository cards, and composes the landing page withRepositoryHomeandOpenWikiFooter.app/components/repository-home.tsx— Implements the client-side repository entry, search, featured card refresh, routing, and home-page interaction state.
System-to-Code Mapping
At the repository level, OpenWiki is a TypeScript application built on Next.js, React, and eve. The package metadata declares Node >=24, scripts for next dev --turbopack, next build, next start, and tsc --noEmit, and dependencies that match the README’s system description: next, react, react-dom, eve, ai, @neondatabase/serverless, @vercel/blob, @vercel/oidc, and UI/rendering libraries such as react-markdown, remark-gfm, rehype-pretty-code, and shiki. Those dependencies show the intended shape of the system: a modern Next.js web app, an agent runtime, serverless data storage, generated artifact storage, authentication support for internal calls, and markdown rendering for published documentation.
Sources: package.json, README.md
The README’s deployment model maps directly to that dependency set. A one-click Vercel deployment provisions Neon Postgres for repository metadata, jobs, revisions, and chat state, plus Vercel Blob for generated wiki artifacts. GITHUB_TOKEN is optional but recommended because public GitHub API limits can otherwise constrain indexing. The README also states that public deployments intentionally reject private repositories, which defines an important security and product boundary: OpenWiki is built for public source-grounded documentation, not as a private-code ingestion service for arbitrary hosted deployments.
Sources: README.md
The home page code maps the first interaction into concrete UI state. RepositoryHome receives initialFeaturedRepositories, keeps a controlled repository input, and derives whether the current text should be treated as a search query by checking input length and parseGitHubRepoUrl. When the user types a non-URL query of at least two characters, the component uses an abortable fetch to /api/repositories/search and updates search results. When featured cards need fresher data, it separately calls /api/repositories/featured with cache: "no-store". These are overview-level clues about the public API surfaces that support the landing experience.
Sources: app/components/repository-home.tsx
Navigation is also encoded in the home component. It imports useRouter, useSearchParams, Link, getRepoHref, and parseGitHubRepoUrl, which reflects the flow from user input to route selection. The component initializes its input from the q query parameter, so search state can be URL-addressable. It also imports branded home-page elements such as OpenWikiHeroLogo and OpenWikiNavbar, and UI primitives such as cards and inputs. The overview takeaway is that the landing page is not a static marketing-only page; it is the operational front door for repository lookup, repository route construction, and discovery.
Sources: app/components/repository-home.tsx
Execution Flow
A typical hosted flow starts with deployment. The README’s deploy button points to a Vercel clone flow that requests the expected storage integrations. After deployment, an operator opens the app and visits a route like /vercel/next.js, or a user enters a GitHub repository URL on the home page. If the repository is not already indexed, other parts of the application create or resume an indexing job. The README summarizes what that job ultimately does: plan an outline, write cited pages, publish the wiki, and keep it fresh on later refreshes.
Sources: README.md, app/components/repository-home.tsx
A typical local flow starts with pnpm install, vercel link, vercel env pull .env.local --yes, and pnpm dev. The local instructions matter for contributors because the app depends on environment-backed services, not only in-memory state. The README also documents OPENWIKI_LOCAL_ARTIFACTS=1 pnpm dev for isolated smoke tests that write artifacts to disk, with the explicit warning that local artifacts should be used only with an isolated local database because shared deployments cannot read files from a developer machine.
Sources: README.md
Once the user reaches the home page, the client experience balances static rendering with dynamic data. app/page.tsx provides initial featured repository cards to RepositoryHome, while the client component refreshes featured metadata from /api/repositories/featured after mount. Repository search follows a similar progressive approach: the input is immediate, the query is delayed, the fetch is abortable, and status messages are stored separately from results. This keeps the home page responsive while avoiding unnecessary requests for short strings or already-parseable GitHub repository URLs.
Sources: app/page.tsx, app/components/repository-home.tsx
Operational Expectations
OpenWiki has a small set of required services but a broad runtime responsibility. The README marks DATABASE_URL as required for repositories, jobs, revisions, and chat sessions, and BLOB_STORE_ID as required for the Vercel Blob store that holds wiki artifacts. It also names BLOB_READ_WRITE_TOKEN for local Blob access, OPENWIKI_LOCAL_ARTIFACTS for isolated local smoke tests, GITHUB_TOKEN for higher public GitHub limits, and OPENWIKI_DISABLE_REPOSITORY_CREATION for read-only public deployments. These variables express the platform boundary: metadata and coordination live in Postgres, generated documentation lives in Blob storage or local artifacts, and GitHub access remains public-repository oriented.
Sources: README.md
The package scripts define the contributor loop. pnpm dev runs the Next.js development server with Turbopack, pnpm build creates a production build, pnpm start serves that production build, and pnpm typecheck runs TypeScript without emitting files. Because the package requires Node >=24, contributors should align local and deployed runtime versions before debugging framework or dependency behavior. The declared dependencies also indicate that UI rendering, markdown rendering, storage, analytics, speed insights, and the eve agent runtime are all first-class parts of the application rather than optional add-ons.
Sources: package.json
Next Steps
Start with the workflow page that matches your task. If you are deploying, read the deployment, storage setup, and environment variable pages together so the Vercel, Neon, Blob, and GitHub-token assumptions are clear. If you are contributing to wiki generation, continue with the application architecture and wiki generation pipeline pages to understand how the Next.js routes hand work to the eve-backed indexing system. If you are changing the landing page or repository discovery experience, read the repository search and creation page alongside the repository home components page, because RepositoryHome is where the overview-level product flow becomes concrete UI behavior.
Sources: README.md, app/page.tsx, app/components/repository-home.tsx