Strapi Architecture — Node.js, Koa, Database, and Plugin System Explained

In this tutorial, you will learn how Strapi is built on Node.js with the Koa framework, how it uses SQLite or PostgreSQL for storage, and how its plugin system and middleware stack process API requests from end to end.

What You'll Learn

• The technology stack Strapi is built on (Node.js, Koa, Knex.js, React)
• How the request lifecycle works from API call to database response
• The difference between SQLite (development) and PostgreSQL (production)
• How Strapi core, plugins, and extensions fit together
• The admin panel architecture (React frontend + Node.js backend)
• How the Content-Type Builder generates database schemas and API routes

Why It Matters

Understanding Strapi's architecture helps you debug issues, optimize performance, and extend Strapi with custom code. When something breaks, you need to know which layer is responsible. When you need to add a feature, you need to know where to put your code. This knowledge separates users who struggle with every problem from developers who solve them confidently.

Real-World Use

A production Strapi deployment serves 10,000 API requests per minute. A sudden spike in response times has everyone worried. Without understanding the architecture, you would randomly check database queries, Node.js memory, and network latency hoping to find the issue. With architectural knowledge, you know to check the middleware stack for a misconfigured rate limiter, the database connection pool for exhausted connections, and the Koa error handler for swallowed exceptions.

Learning Path

flowchart LR
  A["What is Strapi?"] --> B["Strapi Architecture
-- You are here"]:::current
  B --> C["Quick Start"]
  C --> D["Strapi Admin"]
  D --> E["Content Types"]
  E --> F["Fields"]
  F --> G["Relations"]

  classDef current fill:#4945ff,color:#fff,stroke-width:2px

The Technology Stack

Strapi is built on a modern Node.js stack with these core components:

• Runtime: Node.js (v18 or later required)
• HTTP Framework: Koa (lightweight, modern alternative to Express)
• Database Layer: Knex.js query builder with Bookshelf ORM (Strapi 4) or Knex directly (Strapi 5)
• Admin Panel: React single-page application
• Plugin System: Modular npm packages with server and admin code
• API Layer: Auto-generated REST and GraphQL endpoints

Koa Framework

Koa is a lightweight HTTP framework created by the same team behind Express. Unlike Express, which has a rich middleware system with callback-based error handling, Koa uses async/await throughout and has a cleaner middleware pattern.

// Koa middleware runs in a stack-like order (onion model)
// Request comes in -> middleware 1 -> middleware 2 -> route handler
// Route handler response -> middleware 2 -> middleware 1 -> response goes out

// Strapi uses this pattern for its middleware stack
// cors -> rate-limit -> body-parser -> query-parser -> route-handler

Strapi chose Koa over Express because Koa's async middleware pattern is cleaner for the complex middleware chains that Strapi needs. Every API request passes through multiple middleware layers before reaching the controller.

Database Support

Strapi supports three database systems:

In development, Strapi creates a .tmp/data.db SQLite file automatically. In production, you configure PostgreSQL through environment variables.

// config/database.js — PostgreSQL configuration
module.exports = ({ env }) => ({
  connection: {
    client: "postgres",
    connection: {
      host: env("DATABASE_HOST", "localhost"),
      port: env.int("DATABASE_PORT", 5432),
      database: env("DATABASE_NAME", "strapi"),
      user: env("DATABASE_USERNAME", "strapi"),
      password: env("DATABASE_PASSWORD", "password"),
      ssl: env.bool("DATABASE_SSL", false),
    },
    pool: {
      min: 2,
      max: 10,
    },
  },
});

The pool settings control how many database connections Strapi maintains. A pool of 2-10 is sufficient for most projects. High-traffic sites might need 20-50 connections.

Plugin System Architecture

Strapi plugins are self-contained npm packages that add functionality. Each plugin has two parts:

• Server code: Controllers, services, models, policies, middlewares
• Admin code: React components, pages, reducers, translations

// Plugin folder structure
// src/plugins/my-plugin/
//   server/
//     controllers/   -- API endpoint handlers
//     services/      -- Business logic
//     content-types/ -- Custom content type definitions
//     middlewares/   -- Plugin-specific middleware
//     policies/      -- Access control policies
//     bootstrap.js   -- Runs when Strapi starts
//     register.js    -- Runs during plugin registration
//     destroy.js     -- Cleanup on Strapi shutdown
//   admin/
//     src/
//       components/  -- React components
//       pages/       -- Admin panel pages
//       index.js     -- Plugin entry point

This separation means plugins can extend both the API and the admin panel. The SEO plugin, for example, adds metadata fields to the content editor (admin) and serves SEO metadata through the API (server).

Request Lifecycle

When a client makes an API request, it passes through these layers:

// 1. HTTP Request from client (curl, fetch, browser)
//    GET /api/articles?populate=author

// 2. Koa middleware stack (config/middlewares.js)
//    cors, rate-limit, body-parser, query-parser, logger

// 3. Router matches the route
//    /api/articles -> article controller

// 4. Controller handles the request
//    Calls the article service

// 5. Service contains business logic
//    Filters, populates relations, paginates

// 6. Database query via Knex.js
//    SELECT * FROM articles LEFT JOIN authors...

// 7. Response transformation
//    Formats data according to Strapi response format

// 8. HTTP Response back to client
//    { data: [...], meta: { pagination: {...} } }

Understanding this flow helps you know where to add custom logic. Want to log every request? Add middleware. Want to modify data before saving? Use lifecycle hooks. Want to transform the response format? Override the controller.

Admin Panel Architecture

The Strapi admin panel is a React single-page application. When you visit /admin, Strapi serves a React app that communicates with the backend through API calls.

The admin panel includes:

• Content Manager: CRUD interface for your content types
• Content-Type Builder: Visual schema designer
• Media Library: File upload and management
• Settings: Roles, permissions, API tokens, internationalization
• Plugins: Interface for installed plugins

The admin panel communicates with the backend through the same API your frontend will use, plus some admin-specific endpoints.

Core vs Plugins

Strapi's core is intentionally lean. It provides:

• The Koa server and middleware stack
• The Content-Type Builder engine
• Basic auth and user management
• The plugin system

Everything else is a plugin:

• GraphQL (separate plugin, not in core)
• SEO (separate plugin)
• Internationalization (separate plugin)
• Email (separate plugin)
• Upload providers (separate plugins)

This modularity means you only install what you need. A simple project with REST API and local uploads needs no plugins at all.

Common Mistakes

1. Using SQLite in production. SQLite does not handle concurrent writes. When multiple users create content simultaneously, you get database lock errors. Always use PostgreSQL or MySQL in production.

2. Not understanding the middleware order. Custom middleware added in the wrong position can break CORS, authentication, or body Parsing. Middleware runs in the order listed in config/middlewares.js.

3. Trying to use Express middleware in Koa. Strapi uses Koa, not Express. Express middleware does not work directly. You need to convert it or use the Koa Adapter. Installing Express middleware packages will cause errors.

4. Overlooking the admin panel's API dependency. If your backend is down, the admin panel shows a blank page or loading spinner indefinitely. The admin panel is not a standalone app.

5. Ignoring database connection pooling. Default pool settings (min: 2, max: 10) work for most sites but can be overwhelmed by traffic spikes. Monitor database connections and adjust the pool size accordingly.

Practice Questions

1. What are the three main database systems Strapi supports, and which should you use in production? Answer: SQLite (development), PostgreSQL (production), MySQL/MariaDB (production). Use PostgreSQL for production due to its full ACID Compliance, concurrent write support, and JSONB features.

2. Explain the onion model of Koa middleware. How does it differ from Express middleware? Answer: Koa middleware runs in a stack-like pattern. Request enters through middleware 1, passes through to middleware 2, reaches the handler, then unwinds back through middleware 2 and middleware 1. Express middleware runs sequentially without returning through the stack.

3. What are the two parts of every Strapi plugin, and what does each contain? Answer: Server code (controllers, services, content types, middlewares) and admin code (React components, pages, reducers).

4. Challenge: Draw the complete request lifecycle for a POST request to create a new article. Include the middleware stack, controller, service, database query, and response transformation. For each step, write one sentence about what happens at that layer.

FAQ

Mini Project

Your task: Create a visual diagram of Strapi's architecture and trace an API request through each layer.

1. Start a new Strapi project (if you have not already) using npx create-strapi-app@latest strapi-demo --quickstart.
2. Create a content type called "Product" with fields for name, price, and description.
3. Make a GET request to http://localhost:1337/api/products and observe the JSON response.
4. Document the request lifecycle by adding a custom middleware that logs each request. Create src/middlewares/request-logger.js with a simple Koa middleware function.
5. Configure the middleware in config/middlewares.js and restart Strapi. Observe the logs in your terminal when you make API requests.

What's Next

Now that you understand Strapi's architecture, proceed to Quick Start where you will create your first Strapi project, set up an admin user, and create your first content type. After that, explore the Strapi Admin panel to learn about content management, settings, and the user interface.

Related lessons:

• Node.js Fundamentals — The runtime behind Strapi
• PostgreSQL — Production database setup
• GraphQL — The alternative API layer