Aviatopia

Aviatopia is an independent aviation knowledge platform I built and maintain. It publishes long-form guides, topic hubs, a structured glossary, reference directories, and curated learning paths for pilots, students, and aviation enthusiasts who want explanations that are technically grounded without assuming expert background from the first paragraph.

It is not a flight school, a news site, or a markdown blog. Content lives in PostgreSQL, renders as server-generated HTML, and connects through an internal graph of topics, articles, glossary terms, and relationships. The live site currently serves roughly 300 published routes across those systems.

Why I built it

Aviation is full of concepts that depend on other concepts. Lift connects to angle of attack. METAR codes connect to weather theory. Airline economics connects to airport operations. Most online resources either flatten that complexity into listicles or jump straight into material written for people who already know the vocabulary.

I wanted a platform that could hold the middle ground: structured enough to learn from, precise enough to trust, and connected enough that a reader can move from a glossary term to a guide to a topic hub without hitting a dead end.

That pushed the product past "publish articles" into real information architecture: topic pillars, start-here guides, cross-links, backlinks, and discovery surfaces that work for humans and crawlers.

My role

I am the founder and primary engineer. I own the public web application, content data model, publishing layer, PostgreSQL schema, SEO infrastructure, glossary linking system, validation tooling, and the editorial pipeline behind the scenes. The project is built on Atlas, a monorepo foundation I maintain for shared UI, config, and consent tooling.

Product architecture

Aviatopia has five public content systems that work together as a single knowledge product.

Guides are long-form explainers on aerodynamics, weather, aircraft systems, airline and airport operations, and related subjects. Each guide belongs to a topic, carries difficulty metadata, and renders with a table of contents, related guides, see-also links, and optional learning-path navigation.

Topics are hub pages that group related guides, key glossary terms, directories, and learning paths. Each topic can designate a "start here" guide and provides curated entry points into a subject area.

Glossary is a defined-term library with cross-links across the site. Terms connect to topics, related guides, related terms, and inbound backlinks from guides and directories.

Directories are reference lookup pages. Some are database-backed articles; others, like METAR/TAF codes and aircraft registration prefixes, are structured data pages with client-side filtering.

Learning paths are ordered guide sequences for readers who want a path through a subject rather than a single article.

The homepage ties these together: platform orientation, a start-here guide, featured guides, topic collection, learning paths, directories, and glossary discovery. The product reads as a reference platform, not a chronological blog.

Technical architecture

The public site is a Next.js App Router application in TypeScript. Most pages are async Server Components with ISR (revalidate = 3600) on content routes.

Data layer. PostgreSQL via Prisma. Runtime reads go through a ContentRepository abstraction (PrismaContentRepository) warmed at server startup. Content visibility is filtered by environment: production shows only published content; development can include drafts and review items.

Rendering. Guide, glossary, and directory bodies are MDX compiled server-side through a custom renderer with a component map for callouts, steps, FAQs, images, and tables.

UI. Shared primitives from @atlas/ui (Radix-based, Tailwind CSS v4) plus editorial layout components for long-form reading: section rhythm, prose width, content grids, and consistent page chrome.

Publishing flow. When content status changes in the admin app, the platform triggers on-demand ISR revalidation via a secured API route. Pipeline workers can do the same after content generation.

Search. Global header search indexes published content at build time from PostgreSQL. Index-level filters on /guides and /glossary query repository metadata directly on the server.

Observability. Sentry for errors, Web Vitals telemetry, Umami for cookie-free pageviews, optional consent-gated PostHog.

Content graph and information architecture

The interesting part of Aviatopia is not individual pages. It is how they connect.

Topics anchor the taxonomy. Guides have one canonical topic. Glossary terms can attach to multiple topics, including topics inferred from guide relationships.

Article relationships model guide-to-guide edges: cluster siblings, see-also links, recommended next reads, and cross-topic references. These power the "Related guides" and "More in topic" sections on guide pages.

Article-glossary edges record which terms appear in which guides, whether links are explicit or extracted, and how often a term is mentioned. That feeds see-also sections, glossary backlinks, and autolinking decisions.

Learning paths add a curated ordering layer on top of the guide graph.

On the front end, I preload link preview metadata for internal hrefs found in article bodies and related-content sections, so hover previews work without extra client fetches per link. A reader looking up density altitude should be able to reach the weather guide, the performance topic, and related glossary terms without searching blindly.

SEO and crawlability

SEO is centralized in the publishing package, not scattered across page files.

Per-page metadata. Shared generators produce titles, descriptions, canonical URLs, Open Graph tags, and Twitter cards.

Structured data. JSON-LD on major page types: WebSite and Organization on the homepage; Article on guides; DefinedTerm on glossary terms; CollectionPage on topics and directories; BreadcrumbList where appropriate.

Dynamic OG images. Route handlers generate 1200×630 PNG previews per guide, glossary term, and directory via next/og.

Crawl surfaces. Dynamic sitemap built from published DB content, robots.txt, RSS feed of latest guides, and llms.txt for AI crawlers. Retired routes and renamed topics have explicit redirects.

Internal linking. Topic hubs, guide see-also sections, glossary backlinks, directory cross-references, MDX body links, and controlled autolinking.

Validation. The validation layer includes production-readonly checks for links, metadata, glossary graph integrity, search indexing, and build safety. The broader ship gate also supports crawling the live sitemap with Playwright. For a reference platform, crawlability is a product requirement, not an afterthought.

Key engineering decisions

PostgreSQL as the runtime content source

I moved runtime reads to PostgreSQL because a reference platform needs queryable relationships, status workflows, and a single source of truth. Legacy MDX is archived. A ContentRepository interface abstracts reads so the web app, admin, pipeline, and audit tooling share one content source.

Dual-body pattern for linked content

Glossary autolinking must not corrupt the canonical editorial source. The platform stores sourceBody (unlinked canonical MDX) and body (derived output after the linking pipeline). Linking failures revert to source.

Centralized SEO in the publishing package

Metadata, JSON-LD, canonicals, and OG URLs stay consistent across guides, glossary, topics, directories, and learning paths through one set of generators with unit tests alongside.

Glossary autolinking with hard guardrails

A remark plugin matches terms on word boundaries, links the first occurrence per term, caps links per page, skips structural elements, and prevents self-linking. Aliases live in a dedicated table. It scales linking across a large glossary without spamming readers or breaking MDX structure.

Environment-based content visibility

One canonical database with getVisibleStatuses(env) filtering what each environment shows. Admin publish becomes a status change plus ISR revalidation, not a cross-database export.

ISR with on-demand revalidation

Content pages cache on the CDN with hourly revalidation. Admin publish and pipeline workers trigger on-demand revalidation so editorial changes reach readers without a full redeploy.

Production-equivalent validation

Audit and search-index tooling read from the same PostgreSQL content the live site serves, in a read-only production mode. Ship gates should reflect what crawlers and readers actually get.

What I would improve next

Normal product evolution, not a rescue list.

Editorial metadata rigor. Tighten sources and provenance fields across published articles as the catalog grows.

Audit alignment with the content graph. Extend validation to count topic hubs, relationship edges, and glossary mentions alongside markdown body links, so ship gates match how readers actually discover content.

Retire scaffold residue. A few Atlas template routes still ship in the build behind noindex. Gate or remove them the way the flags panel already is.

Performance and accessibility. Re-run Lighthouse and axe against current pages after recent layout work.

Richer aviation data. Live weather feeds, registration databases, and other licensed reference data for directory pages, where accuracy requirements allow.

Onboarding artifacts. Internal diagrams for the content graph and publish flow, useful for portfolio storytelling and for anyone joining editorial or engineering work on the platform.

Result

Aviatopia shows I can build more than a content site. I can build a structured knowledge product with real information architecture, a queryable content graph, and engineering discipline around crawlability and publishing.

It demonstrates product engineering (topic hubs, learning paths, glossary graph), front-end architecture (server-first Next.js, editorial layout system, client islands where they earn their keep), structured content modeling (Prisma relationships, Zod schemas, dual-body linking), SEO as code (metadata helpers, JSON-LD, dynamic OG, sitemap/RSS/llms.txt, production validation tooling), and technical ownership across web, data, publishing, pipeline, and admin.

The platform is live, maintained, and still evolving. That is the point.