diff --git a/README.md b/README.md
index 9826905..4bb8aa8 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,48 @@
 # share-lt
 
-Share Light CMS
+Share Light CMS - Headless CMS with Real-time Publishing
 
 [![status-badge](https://wpk.headshed.dev/api/badges/2/status.svg)](https://wpk.headshed.dev/repos/2) [![Docker Repository on Quay](https://quay.io/repository/marshyon/share-lt/status "Docker Repository on Quay")](https://quay.io/repository/marshyon/share-lt)
- 
 
+## Overview
+
+Share Light is a modern headless CMS built with Laravel 12 that enables real-time content management and automated static site generation. It provides a complete backend solution for content creators and developers who need a robust, scalable CMS with live preview capabilities.
+
+## Architecture
+
+This application runs as a **fat container** orchestrated by **tini** and **supervisor**, managing multiple services:
+
+- **Laravel 12** - Core CMS application with Filament admin interface
+- **PHP-FPM** - PHP process manager
+- **nginx** - Web server and reverse proxy
+- **Queue Worker** - Background job processing
+- **Laravel Reverb** - WebSocket server for real-time communication
+
+### Integration with External Services
+
+- **NATS Messaging** - Publishes messages to NATS streams when content changes
+- **share-lt-astro-consumer** - Companion application that consumes NATS messages to rebuild static sites
+- **Real-time Notifications** - Uses Reverb to send toast alerts to users about build status
+
+## Features
+
+### Content Management
+- **Entry Model** - Core content entities with media library support
+- **Text Widgets** - Reusable content blocks
+- **Categories** - Content organization and taxonomy
+- **Media Library** - Image and file management with Spatie Media Library
+
+### Real-time Publishing Workflow
+1. **Content Updates** - When entries are modified, messages are automatically sent to NATS streams
+2. **Consumer Notifications** - External applications (like share-lt-astro-consumer) listen for these messages
+3. **Preview Generation** - Consumers rebuild preview websites based on content changes
+4. **Status Updates** - Build results are sent back via API
+5. **Live Alerts** - Users receive real-time toast notifications about build status through Reverb
+
+### API & Integration
+- **RESTful API** - Complete API for content retrieval and management
+- **Access Control** - Built-in authorization and authentication
+- **NATS Integration** - Message streaming for distributed architecture
 
 this project is in 'Alpha'