diff --git a/README.md b/README.md
index 2e8bb40..0c1e763 100644
--- a/README.md
+++ b/README.md
@@ -1,73 +1,312 @@
-# django-core-base
+# django-core-base · API Hub Orquestador
 
-// V-Encore Lab: Sistema Automatizado v1.0.4
+> V-Encore Lab — Microservicio principal. Actúa como orquestador y punto de entrada central del ecosistema SaaS.  
+> Puerto por defecto: **8000**
 
-## 🚀 Inicio Rápido (Desarrollo Local)
+---
+
+## Tabla de contenidos
+
+1. [Requisitos previos](#requisitos-previos)
+2. [Inicio rápido — Desarrollo local](#inicio-rápido--desarrollo-local)
+3. [Variables de entorno](#variables-de-entorno)
+4. [Base de datos](#base-de-datos)
+5. [Docker — Producción](#docker--producción)
+6. [Estructura del proyecto](#estructura-del-proyecto)
+7. [Endpoints principales](#endpoints-principales)
+8. [Patrón LogService](#patrón-logservice)
+9. [Flujo de ramas](#flujo-de-ramas)
+10. [Mantenimiento](#mantenimiento)
+
+---
+
+## Requisitos previos
+
+| Herramienta | Versión mínima |
+|-------------|---------------|
+| Python      | 3.11          |
+| pip         | 23+           |
+| Docker      | 24+           |
+| Docker Compose | v2         |
+| Git         | 2.40+         |
+
+---
+
+## Inicio rápido — Desarrollo local
 
-### 1. Clonar y Configurar
 ```bash
+# 1. Clonar
 git clone https://git.v-encore-lab.com/Proyecto-SaaS/django-core-base.git
 cd django-core-base
-cp .env.example .env
-```
 
-### 2. Instalar Dependencias
-```bash
+# 2. Entorno virtual
+python -m venv .venv
+source .venv/bin/activate        # Linux/Mac
+.venv\Scripts\activate           # Windows
+
+# 3. Dependencias
 pip install -r deployments/requirements.txt
-```
 
-### 3. Migraciones de Base de Datos
-```bash
-# Crear y aplicar migraciones para todos los modelos
-python manage.py makemigrations
+# 4. Variables de entorno
+cp .env.example .env
+# Editar .env según el entorno (ver sección Variables de entorno)
+
+# 5. Migraciones (SQLite en local)
+cd app
 python manage.py migrate
 
-# Opcional: Crear superusuario
+# 6. Superusuario (primera vez)
+python manage.py createsuperuser
+
+# 7. Servidor de desarrollo
+python manage.py runserver 0.0.0.0:8000
+```
+
+Accesos:
+- API: http://localhost:8000/api/
+- Admin: http://localhost:8000/admin/
+
+---
+
+## Variables de entorno
+
+Copia `.env.example` a `.env` y ajusta los valores:
+
+| Variable       | Descripción                                      | Ejemplo / Default          |
+|----------------|--------------------------------------------------|----------------------------|
+| `SECRET_KEY`   | Clave secreta Django                             | `django-insecure-...`      |
+| `DEBUG`        | Modo debug                                       | `True` (dev) / `False` (prod) |
+| `ALLOWED_HOSTS`| Hosts permitidos (separados por coma)            | `localhost,127.0.0.1`      |
+| `DB_HOST`      | Host PostgreSQL. **Si no se define → SQLite**    | `localhost` / vacío        |
+| `DB_PORT`      | Puerto PostgreSQL                                | `5432`                     |
+| `DB_NAME`      | Nombre de la base de datos                       | `vencorelab`               |
+| `DB_USER`      | Usuario PostgreSQL                               | `postgres`                 |
+| `DB_PASSWORD`  | Contraseña PostgreSQL                            | `postgres`                 |
+
+---
+
+## Base de datos
+
+### Desarrollo local — SQLite
+
+Si `DB_HOST` **no** está definido en `.env`, Django usa automáticamente SQLite:
+
+```
+app/data/db.sqlite3
+```
+
+```bash
+cd app
+python manage.py migrate          # crea app/data/db.sqlite3
 python manage.py createsuperuser
 ```
 
-### 4. Correr el Servidor
-```bash
-python manage.py runserver
+La carpeta `app/data/` está en `.gitignore` (solo se versiona `.gitkeep`).
+
+### Producción — PostgreSQL
+
+Define `DB_HOST` en `.env` para activar el driver PostgreSQL:
+
+```env
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=vencorelab
+DB_USER=postgres
+DB_PASSWORD=supersecret
 ```
 
-Abrir http://localhost:8000
-
-## 🐳 Docker (Producción/Desarrollo)
-
 ```bash
-docker-compose up --build
+cd app
+python manage.py migrate
 ```
 
-Acceder a:
-- App: http://localhost:8000
-- Admin: http://localhost:8000/admin/
-- DB: localhost:5432 (Postgres)
-
-## 📋 Comandos Django Comunes
+### Comandos útiles de migración
 
 ```bash
-# Verificar configuración
-python manage.py check
+cd app
 
-# Recopilar static files
-python manage.py collectstatic --noinput
+# Ver migraciones pendientes
+python manage.py showmigrations
 
-# Test
-python manage.py test
+# Crear migraciones de una app
+python manage.py makemigrations <app_name>
+
+# Aplicar todas las migraciones
+python manage.py migrate
+
+# Revertir migraciones de una app al estado inicial
+python manage.py migrate <app_name> zero
 ```
 
-## 🔧 Estructura del Proyecto
+---
 
-```
-├── apps/              # Aplicaciones Django
-│   ├── backend_admin/
-│   ├── common/
-│   └── promociones/
-├── core/              # Configuración principal
-├── deployments/       # Docker, requirements prod
-└── manage.py
+## Docker — Producción
+
+```bash
+# Construir e iniciar
+docker-compose up --build -d
+
+# Ver logs
+docker-compose logs -f
+
+# Parar
+docker-compose down
+
+# Parar y eliminar volúmenes (¡cuidado en producción!)
+docker-compose down -v
 ```
 
-## .env Variables
-Ver `.env.example` para configuración.
\ No newline at end of file
+El contenedor expone el puerto **8000**.
+
+Para producción con PostgreSQL, asegúrate de que `.env` tenga `DB_HOST` apuntando al host correcto (puede ser el nombre del servicio en la red Docker).
+
+---
+
+## Estructura del proyecto
+
+```
+django-core-base/
+├── app/
+│   ├── api_config/          # Configuración Django (settings, urls, wsgi)
+│   ├── general/             # App transversal
+│   │   └── utilidades/
+│   │       ├── acciones.py  # LogService — auditoría centralizada
+│   │       └── utils.py     # Utilidades HTTP (get_client_ip, etc.)
+│   ├── backend_admin/       # App admin: modelo Log, endpoints de gestión
+│   ├── common/              # Modelos y utilidades compartidas
+│   ├── promociones/         # App de ejemplo
+│   ├── automatizados/       # Endpoints para Jenkins/automatizaciones
+│   ├── data/                # Directorio de la BD SQLite (gitignored)
+│   │   └── .gitkeep
+│   └── manage.py
+├── deployments/
+│   ├── requirements.txt
+│   └── Dockerfile
+├── docker-compose.yml
+├── .env.example
+└── README.md
+```
+
+---
+
+## Endpoints principales
+
+| Método | Ruta                          | Descripción                       | Auth         |
+|--------|-------------------------------|-----------------------------------|--------------|
+| POST   | `/api/token/`                 | Obtener JWT (login)               | No           |
+| POST   | `/api/token/refresh/`         | Renovar access token              | No           |
+| GET    | `/admin/`                     | Panel de administración Django    | Session      |
+| POST   | `/api/promociones/obtener/`   | Consultar promociones             | JWT Bearer   |
+| GET    | `/api/general/health/`        | Health check                      | No           |
+
+Autenticación: `Authorization: Bearer <access_token>`
+
+---
+
+## Patrón LogService
+
+Todas las vistas deben usar `LogService` para auditoría:
+
+```python
+from general.utilidades.acciones import LogService
+
+class MiVista(APIView):
+    authentication_classes = [JWTAuthentication]
+    permission_classes = [IsAuthenticated]
+
+    def post(self, request):
+        path = '/mi-app/mi-endpoint/'
+
+        # Bloque 1 — Inicio log
+        log_id = LogService.gestionar_log(self, request, path=path)
+
+        try:
+            # Bloque 2 — Limpieza de datos
+            data = request.data
+            LogService.gestionar_log(self, request, log_id=log_id,
+                                     path=path, body_request=data, status_code=100)
+            params = {'campo': data.get('campo')}
+        except Exception as error:
+            response = {'error': str(error)}
+            LogService.gestionar_log(self, request, log_id=log_id,
+                                     path=path, body_response=response, status_code=400)
+            return JsonResponse(response, status=400)
+
+        try:
+            # Bloque 3 — Acción
+            resultado = mi_accion(params)
+            LogService.gestionar_log(self, request, log_id=log_id,
+                                     path=path, body_response=resultado, status_code=200)
+            return JsonResponse(resultado, status=200)
+        except Exception as error:
+            response = {'error': str(error)}
+            LogService.gestionar_log(self, request, log_id=log_id,
+                                     path=path, body_response=response, status_code=500)
+            return JsonResponse(response, status=500)
+```
+
+`LogService` registra automáticamente en la tabla `audit_logs` el usuario, IP, path, request/response y status code.
+
+---
+
+## Flujo de ramas
+
+```
+pre-dev  →  dev  →  master
+```
+
+- `pre-dev`: desarrollo activo, integración de features
+- `dev`: validación previa a producción
+- `master`: rama de producción estable
+
+```bash
+# Crear feature
+git checkout pre-dev
+git checkout -b feature/mi-feature
+
+# Mergear a pre-dev
+git checkout pre-dev
+git merge feature/mi-feature --no-ff
+
+# Promover a dev
+git checkout dev
+git merge pre-dev --no-ff
+
+# Promover a master
+git checkout master
+git merge dev --no-ff
+```
+
+---
+
+## Mantenimiento
+
+```bash
+# Limpiar sesiones expiradas
+cd app && python manage.py clearsessions
+
+# Ver estado de la BD
+cd app && python manage.py dbshell
+
+# Backup SQLite (desarrollo)
+cp app/data/db.sqlite3 app/data/db.sqlite3.bak
+
+# Backup PostgreSQL (producción)
+pg_dump -U postgres vencorelab > backup_$(date +%Y%m%d).sql
+
+# Actualizar dependencias
+pip list --outdated
+pip install -U <paquete>
+pip freeze > deployments/requirements.txt
+
+# Reiniciar contenedor Docker
+docker-compose restart web
+
+# Ver logs del contenedor
+docker-compose logs -f web --tail=100
+```
+
+---
+
+> **V-Encore Lab** — Sistema Automatizado v1.0  
+> Repositorio: `Proyecto-SaaS/django-core-base`