Reorganize Strapi/Redis/Medusa/Algolia documentation (#473)

* feat: cms integrations improvements

* feat: integrations docs improvement

* docs: update theming, update starters page

* feat: update readme

* feat: code reveiw improvemnet

* docs: additional resources and information on the default theme

* docs: update environment variable table formatting in Medusa.js overview

* docs: improve Redis setup instructions and formatting in how-to-setup.md

* docs: update local installation instructions for Redis in how-to-setup.md

* docs: update features overview for SurveyJS integration, including planned ticket system integration

* docs: enhance SurveyJS features documentation

* docs: update code block syntax for theme file path in css-themes.md

* docs: update Redis configuration docs, fix tables, add Contentful theming guide

---------

Co-authored-by: Michal Nowak <michal.nowak@hycom.pl>

Author: tomaszpacior

README.md

@@ -13,6 +13,7 @@ Its flexibility allows for many customizations and lets you build various types
 - **Next.js Frontend Starter** – Robust Next.js-based frontend including basic customer portal pages and content management capabilities.
 - **API Harmonization Server** – **Integration layer** for data aggregation, orchestration and normalization. Provides vendor lock-in safeness and better maintainability.
 - **TypeScript SDK** – Easily interact with the Harmonization Server in the frontend app or any web, mobile, other TS-based apps.
+- **Pre-built Blocks** – 25+ ready-to-use UI blocks with backend logic and SDK clients. Self-contained, reusable components for common features.
 - **Pre-built Integrations** – Ready integrations so that you can set up your solution faster.
 - **Extensibility** – Customize UI components, add new pages, add new API integrations, adapt to your needs.
 
@@ -53,31 +54,49 @@ O2S follows a **monorepo structure** using **Turborepo** for managing apps and i
 
 ```sh
 /apps
-  /frontend             # Next.js frontend
+  /frontend             # Next.js frontend application
   /api-harmonization    # API Harmonization Server (NestJS)
+  /docs                 # Documentation site (Docusaurus)
 
 /packages
-  /ui    # UI component library (shadcn/ui, Tailwind)
+  /blocks/*             # Reusable UI blocks (25+ blocks)
+  /framework            # Core framework modules & SDK
+  /integrations/*       # Integration adapters (Strapi, Contentful, Redis, Algolia, Medusa, Zendesk, mocked)
+  /modules/*            # Feature modules (e.g., surveyjs)
+  /ui                   # Base UI component library (shadcn/ui + Tailwind)
+  /utils/*              # Utility packages
+  /configs/*            # Shared configurations
+  /cli/*                # CLI tools (create-o2s-app)
+  /telemetry            # Telemetry package
 ```
 
 For a detailed breakdown, visit **[Project structure](https://www.openselfservice.com/docs/getting-started/project-structure)**.
 
 ## 🖥️ Demo app
 [![O2S Demo](apps/docs/static/img/o2s-gh-demo.png)](https://demo.openselfservice.com)
 
+## 🧩 Blocks
+
+O2S includes **25+ pre-built blocks** - self-contained, reusable UI components that represent specific features or page sections. Each block includes backend logic (NestJS), frontend component (React), and SDK client.
+
+Examples: article, article-list, ticket-list, order-details, invoice-list, user-account, and more.
+
+For details, visit **[Blocks documentation](https://www.openselfservice.com/docs/main-components/blocks)**.
+
 ## 🔌 Available Integrations
 
 O2S includes pre-built integrations and allows you to extend functionality as needed.
 
 | Integration type/area | Status                                                                                                                                   |
 |-----------------------|------------------------------------------------------------------------------------------------------------------------------------------|
-| **CMS**               | ✅ **StrapiCMS** - available<br/> 🔄 **Contentful** - in progress                                                                         |
+| **CMS**               | ✅ **StrapiCMS** - available<br/> ✅ **Contentful** - available                                                                         |
 | **IAM**               | ✅ **Auth.js** - available<br/> ✅ **Keycloak** - available (not part of O2S, contact us for details)                                      |
 | **Cache**             | ✅ **Redis** - available                                                                                                                  |
 | **Search**            | ✅ **Algolia** - available                                                                                                                |
-| **CRM**               | ✅ **SurveyJS** - ticket submission handling<br/> 🔄 **other CRM solutions** - planned                                                    |
+| **CRM**               | ✅ **Zendesk** - available (tickets)<br/> ✅ **SurveyJS** - ticket submission handling<br/> 🔄 **other CRM solutions** - planned                                                    |
 | **ERP**               | ✅ **Medusa** - via Medusa plugin adding ERP-like features<br/>🔄 **SAP S/4HANA** - In progress (not part of O2S, contact us for details) |
 | **Commerce**          | 🔄 **Medusa** - in progress (basic product information, other areas TBD)                                                                 |
+| **Development**       | ✅ **Mocked** - available (for local development and testing)                                                                           |
 
 
 ## 🔥 Why Open Self Service?

apps/docs/docs/app-starters/dxp/blocks.md

@@ -23,7 +23,7 @@ For a full list of available blocks, together with their configuration, variants
 
 Each block has its own CMS content type defined so that composing pages using blocks is quite straightforward. To use them in your own CMS, take a look into our CMS integrations, where we have prepared ready-to-use exports:
 
-- resources for [Strapi CMS](../../integrations/cms/strapi/getting-started.md)
+- resources for [Strapi CMS](../../integrations/cms/strapi/how-to-setup.md)
 
 ## Storybook
 

apps/docs/docs/app-starters/o2s/blocks.md

@@ -26,7 +26,7 @@ For a full list of available blocks, together with their configuration, variants
 
 Each block has its own CMS content type defined so that composing pages using blocks is quite straightforward. To use them in your own CMS, take a look into our CMS integrations, where we have prepared ready-to-use exports:
 
-- resources for [Strapi CMS](../../integrations/cms/strapi/getting-started.md)
+- resources for [Strapi CMS](../../integrations/cms/strapi/how-to-setup.md)
 
 ## Storybook
 

apps/docs/docs/integrations/cache/redis.md

@@ -0,0 +1,11 @@
+{
+    "label": "Redis",
+    "position": 100,
+    "link": {
+        "type": "doc",
+        "id": "overview"
+    }
+}
+
+
+

apps/docs/docs/integrations/cache/redis/_category_.json

@@ -0,0 +1,62 @@
+---
+sidebar_position: 200
+---
+
+# Features
+
+## Overview
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Cache Operations | ✅ | get, set, del |
+| TTL Management | ✅ | Automatic key expiration |
+| Conditional Caching | ✅ | Toggle via CACHE_ENABLED |
+| Error Handling | ✅ | Graceful fallback on failures |
+| Framework Integration | ✅ | Implements Cache.Service |
+| CMS Integration | ✅ | Used by Strapi/Contentful |
+
+## Cache operations
+
+```typescript
+interface CacheService {
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string): Promise<void>;
+    del(key: string): Promise<void>;
+}
+```
+
+All operations are no-ops when `CACHE_ENABLED=false` or Redis is unavailable.
+
+## TTL management
+
+- All keys expire after `CACHE_TTL` seconds (default: 300)
+- Each key has independent expiration based on when it was set
+- No manual TTL management required
+
+## Connection behavior
+
+- Connection established only when `CACHE_ENABLED=true`
+- No automatic reconnection on connection loss (restart required)
+- All errors are logged but don't crash the application
+
+## CMS integration
+
+CMS integrations cache content using consistent key patterns:
+
+```text
+component-{id}-{locale}
+page-{id}-{locale}
+app-config-{locale}
+```
+
+Cache flow:
+1. Check cache for content
+2. If cached → return immediately
+3. If not cached → fetch from CMS API → store in cache → return
+
+## Limitations
+
+- **No auto-reconnection**: Restart required if connection lost
+- **String values only**: Objects must be serialized (JSON.stringify or flatted)
+- **No tag-based invalidation**: Keys must be deleted manually
+- **Single instance**: No built-in Sentinel/Cluster support

apps/docs/docs/integrations/cache/redis/features.md

@@ -0,0 +1,98 @@
+---
+sidebar_position: 150
+---
+
+# How to set up
+
+## Install
+
+```shell
+npm install @o2s/integrations.redis --workspace=@o2s/api
+```
+
+## Set up Redis instance
+
+You need to set up your own Redis instance. We do not provide a Docker configuration for Redis. For detailed installation and setup instructions, refer to the [official Redis documentation](https://redis.io/docs/).
+
+### Local installation
+
+For local installation instructions, refer to the [official Redis installation guide](https://redis.io/docs/latest/operate/oss_and_stack/install/archive/install-redis/).
+
+### Production
+
+Consider managed services: [Redis Cloud](https://redis.com/cloud), [AWS ElastiCache](https://aws.amazon.com/elasticache/), [Azure Cache](https://azure.microsoft.com/services/cache/), [Google Memorystore](https://cloud.google.com/memorystore).
+
+## Configuration
+
+After installing the package, you need to configure the integration in the `@o2s/configs.integrations` package. This tells the framework to use Redis Cache instead of the default mocked integration.
+
+### Step 1: Update the cache integration config
+
+Open the file `packages/configs/integrations/src/models/cache.ts` and replace the import:
+
+**Before (using mocked integration):**
+
+```typescript
+import { Config, Integration } from '@o2s/integrations.mocked/integration';
+```
+
+**After (using Redis Cache integration):**
+
+```typescript
+import { Config, Integration } from '@o2s/integrations.redis/integration';
+```
+
+The complete file should look like this:
+
+```typescript
+import { Config, Integration } from '@o2s/integrations.redis/integration';
+
+import { ApiConfig } from '@o2s/framework/modules';
+
+export const CacheIntegrationConfig: ApiConfig['integrations']['cache'] = Config.cache!;
+
+export import Service = Integration.Cache.Service;
+```
+
+### Step 2: Verify AppConfig
+
+The `AppConfig` in `apps/api-harmonization/src/app.config.ts` should already reference `Cache.CacheIntegrationConfig`. You don't need to modify this file - it automatically uses the configuration from `@o2s/configs.integrations`.
+
+## Configure environment variables
+
+```env
+CACHE_ENABLED=true
+CACHE_TTL=3600
+CACHE_REDIS_HOST=localhost
+CACHE_REDIS_PORT=6379
+CACHE_REDIS_PASS=REDIS_PASS
+```
+
+### TTL recommendations
+
+- **Short (300-1800s)**: Frequently changing data
+- **Medium (1800-7200s)**: CMS content, API responses
+- **Long (7200-86400s)**: Static configuration
+
+## Verify connection
+
+Start the API Harmonization server. Successful connection logs:
+
+```log
+[REDIS] Successfully connected to redis
+```
+
+Test manually:
+
+```shell
+redis-cli -h localhost -p 6379 -a REDIS_PASS ping
+# Expected: PONG
+```
+
+## Troubleshooting
+
+| Problem                 | Solution                                        |
+| ----------------------- | ----------------------------------------------- |
+| Cannot connect          | Verify Redis is running: `redis-cli ping`       |
+| Authentication failed   | Check `CACHE_REDIS_PASS` matches Redis password |
+| Cache returns undefined | Verify `CACHE_ENABLED=true`                     |

apps/docs/docs/integrations/cache/redis/how-to-setup.md

@@ -0,0 +1,36 @@
+---
+sidebar_position: 100
+---
+
+# Redis Cache
+
+This integration provides caching capabilities using [Redis](https://redis.io/). It implements the framework's `Cache.Service` interface and is used by CMS integrations (Strapi, Contentful) to cache pages, components, and configuration.
+
+## In this section
+
+- [How to set up](./how-to-setup.md) - Installation and configuration guide
+- [Features](./features.md) - Capabilities and cache operations
+- [Usage](./usage.md) - Examples and best practices
+
+## Installation
+
+```shell
+npm install @o2s/integrations.redis --workspace=@o2s/api
+```
+
+## Environment variables
+
+| name             | type    | description                         | required | default |
+|------------------|---------|-------------------------------------|----------|---------|
+| CACHE_ENABLED    | boolean | enables/disables cache              | no       | false   |
+| CACHE_TTL        | number  | key expiration time (seconds)       | no       | 300     |
+| CACHE_REDIS_HOST | string  | Redis host                          | yes      | -       |
+| CACHE_REDIS_PORT | number  | Redis port                          | yes      | -       |
+| CACHE_REDIS_PASS | string  | Redis password                      | no       | -       |
+
+## Quick start
+
+1. Install the package
+2. Set up a Redis instance (see [How to set up](./how-to-setup.md))
+3. Configure environment variables
+4. Set `CACHE_ENABLED=true`