> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt ## Resource: Architecture and Project Structure ## Article: Architecture and Project Structure ## Article Link: https://dev.wix.com/docs/go-headless/develop-your-project/wix-managed-headless/core-concepts/architecture-and-project-structure.md ## Article Content: # Architecture and Project Structure Wix-managed headless projects are built on a modern web development stack that combines the Astro framework, the Vite toolchain, and Wix hosting infrastructure. This article explains how these pieces fit together and what they mean for your project. ## The Astro framework Wix-managed headless projects use [Astro](https://astro.build/) as their foundation. Astro is a JavaScript-based web framework designed for building fast, content-focused websites. There are several reasons Astro is a good fit for headless projects: - **Backend rendering by default**: Astro renders pages on the server, which means faster initial page loads and better SEO without extra configuration. - **Partial hydration**: Astro only sends JavaScript to the browser when a component actually needs interactivity. Static content ships as plain HTML with no JavaScript overhead, resulting in smaller bundle sizes and faster page loads. - **No new language to learn**: Everything in Astro is written in HTML, CSS, and JavaScript. There's no proprietary templating language. - **Framework flexibility**: Astro isn't locked to a single component framework. You can use React, Vue, Svelte, or Solid components alongside plain HTML, or mix and match frameworks in the same project. For example, you might use React for a dynamic shopping cart component while keeping the rest of your product pages in plain Astro. For details on Astro's features and syntax, see the [Astro documentation](https://docs.astro.build/). ## Project structure overview When you create a Wix-managed headless project with the CLI, it generates an Astro project with Wix integration. Here are the key parts of the project: - `src/`: Your source code: Astro pages, components, layouts, and extensions. - `src/extension.ts`: Registers all [extensions](https://dev.wix.com/docs/go-headless/develop-your-project/wix-managed-headless/core-concepts/about-extensions.md) for your project. - `public/`: Static files served at the root of your project, such as images and fonts. - `.wix/`: Wix configuration and environment files. - `astro.config.mjs`: Astro configuration file. - `wix.config.json`: Defines your project's app ID and project ID. - `.env.local`: Environment variables for local development, including authentication credentials. Your frontend is defined by standard Astro files: [pages](https://docs.astro.build/en/basics/astro-pages/), [components](https://docs.astro.build/en/basics/astro-components/), and [layouts](https://docs.astro.build/en/basics/layouts/). Extensions are organized in custom folders under `src/` and registered in the `extension.ts` configuration file. For the complete file structure reference, see [Project Structure](https://dev.wix.com/docs/wix-cli/guides/get-started/project-structure.md) in the CLI documentation. ## The Vite toolchain Under the hood, the Wix CLI uses [Vite](https://vitejs.dev) as its build tool. Vite provides: - **TypeScript support**: Write your code in TypeScript with full IntelliSense and type checking. - **Hot module replacement**: Changes you make to your code are reflected in the browser without a full page reload during local development. - **CSS modules and pre-processors**: Use CSS modules, Sass, Less, or PostCSS out of the box. - **Static asset handling**: Import images and other assets directly in your code. The CLI handles the setup, so you don't need to configure Vite yourself. ## Your project's private app When you create a Wix-managed headless project, the CLI sets up a private app behind the scenes. This app serves 2 important roles: - **Authentication**: The private app acts as the OAuth handler for your project. It's the reason you don't need to manually create an OAuth app or manage client credentials. The CLI configures the app's credentials and stores them in your project's environment variables. - **Extensions**: The private app is where your [extensions](https://dev.wix.com/docs/go-headless/develop-your-project/wix-managed-headless/core-concepts/about-extensions.md) are registered. When you add extensions, they're added to this app. The `extension.ts` file in your project is the configuration file for this app's extensions. The private app is tied to your headless project and can't be shared with other projects or published to the Wix App Market. It exists to power your project's backend capabilities and authentication. You can see the private app's ID in your `wix.config.json` file under the `appId` field. ## Hosting infrastructure Wix-managed headless projects are hosted on Wix serverless infrastructure. You don't manage any servers, containers, or deployment pipelines. The hosting environment provides: - **Global content delivery network (CDN)**: Your project is served from a CDN, ensuring fast load times for visitors worldwide. - **Automatic SSL**: SSL certificates are provisioned and renewed automatically, so your project is always served over HTTPS. - **Serverless architecture**: Scaling and resource allocation are handled automatically. Your project scales up during traffic spikes and scales down when demand decreases. - **Session management middleware**: A built-in middleware manages session tokens and cookies for site visitors. This is what enables features like persistent shopping carts and seamless authentication without you writing session management code. For details on building and deploying to this infrastructure, see [Development, Build, and Deployment](https://dev.wix.com/docs/go-headless/develop-your-project/wix-managed-headless/core-concepts/development-build-and-deployment.md). ## See also - [About the Wix CLI](https://dev.wix.com/docs/wix-cli/guides/about-the-wix-cli.md) - [Wix CLI Project Structure](https://dev.wix.com/docs/wix-cli/guides/get-started/project-structure.md) - [Quick Start a Headless Project](https://dev.wix.com/docs/wix-cli/guides/get-started/quick-start-a-headless-project.md) - [Astro documentation](https://docs.astro.build/)