Explore the technical architecture behind AI Educademy: Next.js 15 App Router, next-intl for i18n, MDX content pipeline, git submodules, PWA support, and Vercel deployment.
Building AI Educademy presented a unique technical challenge: create a platform that's accessible to learners worldwide, easy to maintain, and scalable enough to serve millions of users—all while keeping the codebase clean and developer-friendly.
In this deep dive, we'll walk through the architectural decisions that shaped our platform, from our choice of Next.js 15 to how we manage multilingual content with git submodules. Whether you're building an educational platform, a documentation site, or any content-heavy application, you'll find practical insights here.
When we started building AI Educademy, Next.js 14 was the standard. By the time we launched, Next.js 15 was released with significant improvements to the App Router. We made the jump because several factors aligned perfectly with our goals:
Server Components by Default: The Next.js 15 App Router uses Server Components by default, which means we can fetch data directly in our components without extra API routes for simple operations. This reduces complexity and improves performance out of the box.
Incremental Static Regeneration (ISR): Educational content doesn't change constantly, but it does change. ISR allows us to pre-render pages at build time and then revalidate them on a schedule. This means our blog posts, tutorials, and course materials are always fresh without the performance hit of on-demand rendering.
Built-in Optimization: Image optimization, font loading, and code splitting are handled automatically. We didn't have to spend cycles building or configuring these features—they just work.
File-based Routing: The App Router's intuitive file structure makes it obvious where pages and API routes live. New contributors can jump into the codebase and understand the structure immediately.
// Our routing structure is intuitive and scalable
app/
├── [locale]/
│ ├── page.tsx
│ ├── programs/
│ │ ├── page.tsx
│ │ └── [slug]/
│ │ └── page.tsx
│ └── blog/
│ ├── page.tsx
│ └── [slug]/
│ └── page.tsx
├── api/
└── layout.tsx
AI Educademy is built for the global community. Offering content in multiple languages isn't just nice-to-have—it's essential for fulfilling our mission of free AI education for everyone.
We chose next-intl because it:
/en/programs and /es/programas with the same page component)Here's how we structure our i18n setup:
// middleware.ts - Detects user locale and routes accordingly
import { createMiddleware } from 'next-intl/middleware';
export default createMiddleware({
locales: ['en', 'es', 'fr', 'de', 'zh'],
defaultLocale: 'en'
});
export const config = {
matcher: ['/((?!api|_next|.*\\..*).*)']
};
Our translation files are organised by locale and feature:
messages/
├── en/
│ ├── common.json
│ ├── programs.json
│ └── blog.json
├── es/
│ ├── common.json
│ └── ...
└── fr/
└── ...
This approach scales beautifully. Adding a new language means adding a new folder with JSON files—no code changes required.
Here's where things get interesting. We could have used a traditional headless CMS, but we chose MDX because it gives us the best of both worlds: content management that's version-controlled alongside our code, and the ability to embed interactive React components directly in our educational content.
When you read a blog post or tutorial on AI Educademy, you're not just reading static HTML. You might be interacting with:
All of this is possible because we're using MDX. Our content authors can write in Markdown, but developers can pass in custom components:
---
title: "Understanding Neural Networks"
---
# Understanding Neural Networks
<ConceptExplainer concept="neural-networks" />
Neural networks are inspired by how our brains work...
<InteractiveQuiz questionId="nn-101" />
## Real-World Applications
<CodeExample language="python" title="Simple Neural Network" />
To make MDX work smoothly in Next.js 15, we use @next/mdx and configure it in our next.config.js:
// next.config.js
import createMDX from '@next/mdx';
const withMDX = createMDX({
options: {
remarkPlugins: [
// Our custom plugins for syntax highlighting, TOC generation, etc.
],
rehypePlugins: []
}
});
export default withMDX({
pageExtensions: ['ts', 'tsx', 'mdx']
});
Here's a clever architectural decision: our content lives in separate git repositories, pulled into the main application as git submodules.
Why? Because it enables:
Our directory structure looks like:
ai-educademy/
├── content/ (git submodule)
│ ├── blog/
│ │ ├── en/
│ │ ├── es/
│ │ └── fr/
│ ├── programs/
│ │ └── [course content]
│ └── lab/
│ └── [interactive exercises]
├── app/
├── package.json
└── .gitmodules
When we need to update content, we:
# Pull latest content
git submodule update --remote
# Or content authors can PR directly to the content repo
This decoupling has been game-changing for our velocity. Content can be updated without triggering application rebuilds (thanks to ISR), and new programmes can be added by non-engineers.
Education happens on all devices, including low-bandwidth environments. We built AI Educademy as a PWA so learners can:
// next.config.js includes PWA configuration
import withPWA from 'next-pwa';
const withPWA = require('next-pwa')({
dest: 'public',
disable: process.env.NODE_ENV === 'development'
});
Our Service Worker strategy is straightforward:
We deploy on Vercel because the integration with Next.js is seamless. Every push to our main branch triggers automatic builds and deployments. More importantly:
Our deployment pipeline looks like:
Git Push → GitHub → Vercel Build → CDN Distribution → Global Users
For content updates specifically, we've set up webhooks so that when our content submodule is updated, Vercel automatically rebuilds the site with fresh content.
All of this architecture works together to create a platform that performs at the top level. Our real-world metrics:
These aren't vanity metrics—faster sites means more learners can access our content, especially those on mobile networks or in regions with limited infrastructure.
The entire codebase is open source. If you want to see how all these pieces work together, you can explore the repository, contribute improvements, or fork it for your own educational platform.
The architecture we've described here isn't proprietary—it's built on solid, widely-adopted open source tools. The community benefits from our learnings, and we benefit from community contributions.
Whether you're building an educational platform or any content-heavy application, consider:
AI Educademy represents our commitment to accessible, performant, and maintainable tech infrastructure for education. If you're interested in any of these technologies or want to contribute, our code is open source and waiting for your collaboration.
Want to try our platform? Explore our programmes | Visit the Lab | Read more about our mission