opencomponents · ricardo-devis-agullo · Jul 18, 2026 · Jul 18, 2026
diff --git a/website/docs/components/cli.md → website/docs/building/cli.md b/website/docs/components/cli.md → website/docs/building/cli.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 2
----
-
 # Command Line Tool
 
 ## Prerequisites

diff --git a/website/docs/building/debugging.md b/website/docs/building/debugging.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 3
----
-
 # Debugging
 
 ## General Debugging Principles

diff --git a/website/docs/components/getting-started.md → website/docs/building/getting-started.md b/website/docs/components/getting-started.md → website/docs/building/getting-started.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 1
----
-
 # Getting Started
 
 ## Prerequisites
@@ -152,7 +148,7 @@ Explore these example repositories to see OpenComponents in action:
 
 ## Troubleshooting Common Issues
 
-- For installation problems, component creation errors, or dev-server hiccups, refer to the in-depth [CLI guide](cli.md#troubleshooting) which contains up-to-date solutions.
+- For installation problems, component creation errors, or dev-server hiccups, refer to the in-depth [CLI guide](cli#installation-troubleshooting) which contains up-to-date solutions.
 
 ## Next Steps
 
@@ -161,7 +157,7 @@ Once you've created your first component:
 1. **[Learn the CLI](cli)** - Master all available commands
 2. **[Understand package.json structure](package.json-structure)** - Configure your component properly
 3. **[Add server-side logic](the-server.js)** - Make your component dynamic
-4. **[Publish to a registry](publishing-to-a-registry)** - Share your component
+4. **[Publish to a registry](../registry/publishing-to-a-registry)** - Share your component
 5. **[Explore client-side operations](../consumers/rendering-lifecycle)** - Advanced browser integration
 
 For a complete hands-on tutorial, see our [Quick Start Tutorial](../quick-start-tutorial).
diff --git a/website/docs/building/index.md b/website/docs/building/index.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 0
----
-
 # Building Components
 
 Everything you need to create production-ready micro-frontends.

diff --git a/...docs/components/package.json-structure.md → ...e/docs/building/package.json-structure.md b/...docs/components/package.json-structure.md → ...e/docs/building/package.json-structure.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 3
----
-
 # Structure of package.json
 
 ## Overview
@@ -316,5 +312,5 @@ ls -la public/
 
 - **[Learn server.js structure](the-server.js)** - Add dynamic data to your components
 - **[Understand CLI commands](cli)** - Master component development workflow
-- **[Publishing guide](publishing-to-a-registry)** - Deploy your components
+- **[Publishing guide](../registry/publishing-to-a-registry)** - Deploy your components
 - **[Template system](../building/template-system)** - Choose the right template type
diff --git a/website/docs/building/template-system.md b/website/docs/building/template-system.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 2
----
-
 # Template System
 
 ## Introduction
@@ -42,7 +38,7 @@ Usage:
 $ oc init myComponent oc-template-jade  # Legacy template - ES6 recommended for new components
 ```
 
-Check the [CLI documentation](/docs/components/cli) for more details.
+Check the [CLI documentation](/docs/building/cli) for more details.
 
 ### On the Registry
 
@@ -56,7 +52,7 @@ templates: [require('oc-template-extra'), require('oc-template-plus')]
 }
 ```
 
-Check the [registry configuration guide](/docs/registry/registry-configuration#registry-configuration) for more details.
+Check the [registry configuration guide](/docs/registry/registry-configuration#configuration-reference) for more details.
 
 ### Client-side rendering
 

diff --git a/website/docs/components/the-server.js.md → website/docs/building/the-server.js.md b/website/docs/components/the-server.js.md → website/docs/building/the-server.js.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 4
----
-
 # Server-side Logic (server.js / entry.server.ts)
 
 This guide covers how to add server-side logic to your components. Modern components use `src/entry.server.ts` with the `Server` API, while the legacy `server.js` with callbacks is still supported for backwards compatibility.
@@ -288,9 +284,9 @@ Context aggregates request data, and the registry's context. It consists of the
 | ------------------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `acceptLanguage`   | `array of objects`   | represents parsed `accept-language` part of the request header sorted by quality. More details [here](https://github.com/opentable/accept-language-parser)                                                                                                                    |
 | `baseUrl`          | `string`             | represents public registry base url. This is required when we want to nest components that are hosted in the same registry for client-side rendering                                                                                                                          |
-| `env`              | `object`             | represents the registry environment variables. The registry's admin [can share here arbitrary data](/docs/registry/registry-configuration#registry-configuration)                                                                                                             |
+| `env`              | `object`             | represents the registry environment variables. The registry's admin [can share here arbitrary data](/docs/registry/registry-configuration#configuration-reference)                                                                                                             |
 | `params`           | `object`             | represents parameters extracted from the query string                                                                                                                                                                                                                         |
-| `plugins`          | `array of functions` | [custom functionalities that extend the registry](/docs/registry/registry-configuration#plugins). Note: if a component needs a plugin, [it needs to be declared in the component's package.json](/docs/components/getting-started#structure-of-the-package)                   |
+| `plugins`          | `array of functions` | [custom functionalities that extend the registry](/docs/registry/registry-configuration#plugins). Note: if a component needs a plugin, [it needs to be declared in the component's package.json](/docs/building/getting-started#structure-of-the-package)                   |
 | `renderComponent`  | `function`           | Needed to do server-side nested renderings. [renderComponent API](#rendercomponent-api)                                                                                                                                                                                       |
 | `renderComponents` | `function`           | Needed to do server-side nested renderings. [renderComponents API](#rendercomponents-api)                                                                                                                                                                                     |
 | `requestHeaders`   | `object`             | represents the original request headers. When component is rendered client side this will be what is sent from the browser, when rendered server side, using oc-client, this will contain whatever the client has been configured to forward                                  |
@@ -523,5 +519,5 @@ module.exports.data = function (context, callback) {
 
 - **[Learn package.json structure](package.json-structure)** - Configure your component properly
 - **[Master the CLI](cli)** - Efficient development workflow
-- **[Publishing guide](publishing-to-a-registry)** - Deploy your components
+- **[Publishing guide](../registry/publishing-to-a-registry)** - Deploy your components
 - **[Client-side operations](../consumers/rendering-lifecycle)** - Browser integration patterns
diff --git a/website/docs/components/_category_.json b/website/docs/components/_category_.json
diff --git a/website/docs/concepts/architecture-overview.md b/website/docs/concepts/architecture-overview.md
@@ -1,104 +1,20 @@
----
-sidebar_position: 3
----
-
 # Architecture Overview
 
-<div className="hero-section">
-
-## How OpenComponents Works
-
-OpenComponents is a **micro frontend architecture** that breaks down monolithic applications into independently deployable, reusable components that teams can own and maintain autonomously.
-
-</div>
-
-## Conceptual Overview
-
-<div className="concept-example">
-
-### 🛒 **Real-World Example: E-commerce Platform**
-
-Instead of building one massive application, imagine decomposing it into independent components:
-
-<div className="component-breakdown">
-
-**🏠 Header Component** → Platform Team
-- Navigation, search, user menu
-- Deployed independently
-- Shared across all pages
-
-**📦 Product Listing** → Catalog Team  
-- Product cards, filters, pagination
-- A/B test new layouts
-- Optimized for performance
-
-**🛒 Shopping Cart** → Commerce Team
-- Cart state, checkout flow
-- Payment integrations
-- Independent scaling
-
-**👤 User Profile** → Identity Team
-- Authentication, preferences
-- Privacy controls
-- Account management
-
-</div>
-
-**The Result:** Each team develops, tests, and deploys independently while users see a seamless, integrated experience.
-
-</div>
-
-## Benefits of This Approach
-
-<div className="benefits-overview">
-
-### 🚀 **Team Independence**
-- **Autonomous development** - No coordination bottlenecks
-- **Technology flexibility** - React, Vue, ES6, or any framework per component  
-- **Independent deployments** - Release on your own schedule
-- **Clear ownership** - Teams own components end-to-end
-
-### 📈 **Scalability & Performance**
-- **Component-level scaling** - Scale based on actual usage patterns
-- **CDN optimization** - Automatic asset distribution globally
-- **Server-side rendering** - SEO and performance without Node.js requirements
-- **Caching strategies** - Intelligent caching at multiple levels
-
-### 🔄 **Gradual Migration**
-- **Start small** - Begin with one component, expand gradually
-- **No big bang** - Migrate from monolith incrementally
-- **Risk mitigation** - Test architecture with non-critical components
-- **Backward compatibility** - Existing applications continue working
-
-</div>
-
-## Why Choose OpenComponents?
-
-### Team Independence
+OpenComponents breaks down monolithic frontends into independently deployable, reusable components that teams can own and maintain autonomously. For the motivation behind this, see [Why OpenComponents?](why-opencomponents).
 
-- **Autonomous development**: Teams work on their components without blocking each other
-- **Technology flexibility**: Use React, Vue, ES6, or any framework per component
-- **Independent deployments**: Release updates without coordinating with other teams
-- **Clear ownership**: Each team owns their components end-to-end
+## Example decomposition
 
-### Gradual Migration
+A typical e-commerce page could be decomposed into independent components, each owned by a different team:
 
-- **Start small**: Begin with one component and gradually expand
-- **No big bang**: Migrate from monolith to micro frontends incrementally
-- **Risk mitigation**: Test the architecture with non-critical components first
-- **Backward compatibility**: Existing applications continue working during migration
+- **Header** (Platform team) – navigation, search, user menu; deployed independently, shared across pages.
+- **Product listing** (Catalog team) – product cards, filters, pagination.
+- **Shopping cart** (Commerce team) – cart state, checkout flow, payment integrations.
+- **User profile** (Identity team) – authentication, preferences, account management.
 
-### A/B Testing and Experimentation
-
-- **Component-level testing**: Test different versions of individual components
-- **Isolated experiments**: Changes to one component don't affect others
-- **Faster iteration**: Deploy and test new features quickly
-- **Data-driven decisions**: Measure impact of component changes independently
+Each team develops, tests, and deploys independently, while users see one seamless, integrated page.
 
 ## System Architecture
 
-<div className="architecture-diagram">
-
 ```mermaid
 graph TB
     subgraph "Development"
@@ -140,53 +56,12 @@ graph TB
     style CLI fill:#9C27B0
 ```
 
-</div>
-
-### 🏗️ **Core Components**
-
-<div className="architecture-components">
-
-<div className="arch-component">
-
-#### **🛠️ CLI & Development Tools**
-- Component scaffolding and development
-- Local testing with hot reload
-- Publishing and version management
-- Built-in preview and debugging tools
-
-</div>
-
-<div className="arch-component">
-
-#### **🌐 Registry (REST API)**
-- Central component catalog and metadata
-- Version management and resolution
-- Authentication and access control
-- Component rendering and serving
-
-</div>
-
-<div className="arch-component">
-
-#### **📦 Component Library**
-- Immutable component storage
-- Version history and artifacts
-- Dependency management
-- Backup and disaster recovery
+### Core components
 
-</div>
-
-<div className="arch-component">
-
-#### **🚀 CDN & Asset Distribution**
-- Global static asset delivery
-- Automatic optimization and compression
-- Edge caching for performance
-- Bandwidth cost optimization
-
-</div>
-
-</div>
+- **CLI & development tools** – component scaffolding, local dev server with hot reload, publishing, preview and debugging.
+- **Registry (REST API)** – component catalog and metadata, version resolution, authentication, rendering.
+- **Component library** – immutable storage of published component versions and artifacts.
+- **CDN & asset distribution** – static assets (JS, CSS, images) served from CDN with edge caching.
 
 ## Publishing Workflow
 
@@ -293,27 +168,7 @@ Results:
 
 **Best Practices**:
 
-- ✅ **Use semantic versioning**: `~1.2.0` instead of `1.2.4`
-- ✅ **Short polling intervals**: 5-second sync reduces inconsistency window
-- ✅ **Monitoring & alerting**: Track registry sync health
-- ✅ **Graceful degradation**: Serve cached versions during outages
-
-### Advanced Distribution Features
-
-**🔄 Automatic Failover**
-
-- Registry instances automatically retry failed CDN connections
-- Components remain available from memory cache during outages
-- Health checks detect and route around unhealthy instances
-
-**📊 Monitoring Integration**
-
-- Registry publishes events for sync failures and recoveries
-- Metrics tracking for component usage and performance
-- Alerting for version inconsistencies across regions
-
-**🚀 Performance Optimization**
-
-- Template deduplication across component versions
-- Intelligent caching based on usage patterns
-- CDN edge caching for global distribution
+- **Use semantic versioning**: prefer `~1.2.0` over pinning `1.2.4`, so consumers tolerate a registry serving a slightly older patch during the sync window
+- **Short polling intervals**: the default 5-second `pollingInterval` keeps the inconsistency window small
+- **Monitoring**: subscribe to the [registry's events](../registry/registry-configuration#registryoneventname-callback) to track sync health
+- **Fallback registries**: configure [`fallbackRegistryUrl`](../registry/registry-configuration#configuration-reference) so requests can be served by a secondary registry if a component isn't found locally