diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b585ac1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,184 @@
+# SAPIENS Web3
+
+Latest iteration of SAPIENS Web platform with cutting-edge features and optimizations.
+
+## Overview
+
+SAPIENS Web3 represents the most advanced version of the SAPIENS platform, incorporating modern web technologies, enhanced user experience, and additional features including public asset serving and improved content delivery.
+
+## Tech Stack
+
+### Frontend
+- **Framework**: React 18.3 with Vite 5.4
+- **Language**: TypeScript 5.6
+- **Styling**: Tailwind CSS 3.4 with shadcn/ui components
+- **State Management**: TanStack React Query 5.60
+- **Routing**: Wouter 3.3
+- **UI Library**: Radix UI primitives
+
+### Backend
+- **Runtime**: Node.js with Express 4.21
+- **Database**: PostgreSQL with Drizzle ORM 0.44
+- **Authentication**: Passport.js with local and OpenID strategies
+- **Session**: express-session with PostgreSQL store
+
+## Project Structure
+
+```
+sapiens-web3/
+├── client/                   # React frontend
+│   ├── src/
+│   │   ├── components/      # UI components
+│   │   ├── hooks/          # Custom React hooks
+│   │   └── lib/            # Utilities
+├── server/                   # Express backend
+│   ├── index.ts            # Server entry point
+│   ├── routes.ts           # API routes
+│   └── db/                 # Database schemas
+├── public/                   # Static assets
+├── scripts/                  # Build and utility scripts
+├── shared/                   # Shared types and utilities
+└── dist/                    # Build output
+```
+
+## Key Features
+
+### New in Web3
+- Public asset serving with optimized delivery
+- Enhanced media handling
+- Improved caching strategies
+- Advanced API endpoints
+- Better SEO optimization
+- Progressive Web App (PWA) support
+
+### Improvements over Web2
+- Enhanced performance with optimized bundling
+- Improved database query optimization
+- Better error handling and monitoring
+- Advanced authentication features
+- Enhanced security measures
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+ and npm/yarn
+- PostgreSQL 14+
+
+### Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Set up database
+npm run db:push
+```
+
+### Environment Variables
+
+Create a `.env` file:
+
+```env
+DATABASE_URL=postgresql://user:password@localhost:5432/sapiens_db3
+SESSION_SECRET=your-session-secret
+NODE_ENV=development
+PORT=5000
+PUBLIC_URL=http://localhost:5000
+```
+
+### Development
+
+```bash
+# Start development server
+npm run dev
+
+# Type checking
+npm run check
+
+# Run utility scripts
+npm run scripts
+```
+
+### Production Build
+
+```bash
+# Build the application
+npm run build
+
+# Start production server
+npm start
+```
+
+## Database Management
+
+```bash
+# Push schema changes to database
+npm run db:push
+
+# Generate migrations
+drizzle-kit generate
+
+# Run migrations
+drizzle-kit migrate
+```
+
+## API Endpoints
+
+Full REST API with extended features:
+- `GET /api/outlets` - List news outlets with filtering
+- `GET /api/outlets/:id/articles` - Get articles with pagination
+- `GET /api/articles/:id` - Get article details with related content
+- `GET /api/categories` - List all categories
+- `GET /api/trending` - Get trending articles
+- `POST /api/auth/login` - User login
+- `POST /api/auth/register` - User registration
+- `POST /api/bookmarks` - Manage user bookmarks
+
+## Public Assets
+
+Static files are served from the `/public` directory and accessible at `/public/*`. This includes:
+- Images
+- Icons
+- Fonts
+- Other static resources
+
+## Performance Optimization
+
+- Code splitting with dynamic imports
+- Image optimization
+- CSS purging in production
+- Gzip compression
+- Browser caching strategies
+
+## Contributing
+
+1. Create a feature branch from `main`
+2. Make your changes following the code style
+3. Run type checking: `npm run check`
+4. Test all features thoroughly
+5. Update documentation if needed
+6. Submit a pull request with clear description
+
+## Migration Guide
+
+### From Web2 to Web3
+1. Update database connection to use new database
+2. Run migrations: `npm run db:push`
+3. Update environment variables
+4. Move static assets to `/public` directory
+5. Test all endpoints and features
+
+## Deployment
+
+For production deployment:
+1. Set `NODE_ENV=production`
+2. Build the application: `npm run build`
+3. Configure reverse proxy (Nginx recommended)
+4. Set up SSL certificates
+5. Configure database connection pooling
+6. Enable monitoring and logging
+
+## License
+
+Proprietary - All rights reserved