diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 58b6935..094aa5c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,15 +1,44 @@
-# Contributing to Plexus
+# 🤝 Contributing to Plexus
 
-Thank you for your interest in contributing to Plexus!
+We maintain high standards for code quality and documentation. Please follow this workflow for all contributions.
 
-## 🤝 How to Contribute
+## 🔄 Development Workflow
 
-1. **Pick a Task**: Check the [Task Tracker](file:///home/sinan/Documents/repositories/local/plexus/docs/tasks.md) for open items.
-2. **Fork & Branch**: Create a new branch for your feature or bugfix.
-3. **Develop**: Follow the [Development Guide](file:///home/sinan/Documents/repositories/local/plexus/docs/development.md).
-4. **Test**: Ensure all tests pass.
-5. **Pull Request**: Submit a PR with a clear description of your changes.
+### 1. Pick a Task
+Before coding, ensure you are working on an assigned task.
+- List tasks: `make task-list`
+- Add a task: `make task-add title="Your Task"`
+- Mark as in-progress: (Update manually in `tasks/tasks.duckdb` or via CLI if implemented).
 
-## 📜 Code of Conduct
+### 2. Implementation
+- Write clean, modular code.
+- Follow the existing design patterns (Vue 3 Composition API, Pinia, Socket.io).
+- Ensure UI changes are mobile-friendly and follow the Discord-inspired aesthetic.
 
-Please be respectful and collaborative. We aim to build a welcoming community for all developers.
+### 3. Verification
+Before committing, you **must** verify your changes:
+- Run linting: `make lint`
+- Run tests: `make test`
+- Manual check: Verify the feature in the browser.
+
+### 4. Commit
+We use **Husky** and **lint-staged** to enforce quality.
+- Your commit will fail if linting or tests do not pass.
+- Use descriptive commit messages (e.g., `feat: add user profiles`, `fix: message alignment`).
+
+### 5. Documentation
+If your change affects the architecture, data model, or API:
+- Update the relevant file in `docs/`.
+- Ensure the root `README.md` is still accurate.
+
+### 6. Finalize Task
+Mark the task as done:
+- `make task-done id=X`
+
+## 🛠 Tooling
+- **Linting**: ESLint for JS/Vue, Ruff for Python.
+- **Testing**: Mocha for backend integration tests.
+- **Automation**: Use the `Makefile` for all common operations.
+
+---
+Thank you for helping make Plexus better!
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..496be54
--- /dev/null
+++ b/README.md
@@ -0,0 +1,66 @@
+# 🌌 Plexus
+
+Plexus is a premium, decentralized-inspired chat application built with **Vue 3**, **Node.js**, **Socket.io**, and **DuckDB**. It features a sleek Discord-style interface, real-time messaging, and social profiles with customizable "walls".
+
+![Desktop View](file:///home/sinan/.gemini/antigravity/brain/d2723a70-2b81-4f4a-b974-6f0dc17d1fae/desktop_view_1768342632058.png)
+
+## 🚀 Key Features
+
+- **💎 Premium UI**: Discord-inspired dark theme with glassmorphism and smooth animations.
+- **📱 Mobile Ready**: Fully responsive layout with adaptive components.
+- **⚡ Real-time Social**: Instant messaging, reactions, and user profiles with social walls.
+- **🚦 Transaction Lifecycle**: Simulated blockchain transaction states (Pending, Validated, Failed) with LED indicators.
+- **🛠 Robust Tooling**: Automated linting, testing, and a custom internal task tracker.
+
+## 🛠 Tech Stack
+
+- **Frontend**: Vue 3, Pinia, Tailwind CSS, Lucide Icons.
+- **Backend**: Node.js, Express, Socket.io.
+- **Database**: DuckDB (Fast, analytical, and serverless-friendly).
+- **Automation**: Makefile, Husky, Lint-staged, Ruff (Python), ESLint (JS).
+
+## 📖 Documentation
+
+Explore our detailed documentation in the `docs/` directory:
+
+- [🏗 Architecture](file:///home/sinan/Documents/repositories/local/plexus/docs/architecture.md) - High-level system design.
+- [📂 Structure](file:///home/sinan/Documents/repositories/local/plexus/docs/structure.md) - Directory and file organization.
+- [⚙️ Functions & API](file:///home/sinan/Documents/repositories/local/plexus/docs/functions.md) - Socket events and backend logic.
+- [📊 Data Model](file:///home/sinan/Documents/repositories/local/plexus/docs/data-model.md) - Database schema and migrations.
+- [📈 Scalability](file:///home/sinan/Documents/repositories/local/plexus/docs/scalability.md) - Future roadmap and scaling strategies.
+- [📝 Task Tracker](file:///home/sinan/Documents/repositories/local/plexus/docs/tasks.md) - How to use the internal task management tool.
+
+## 🚦 Quick Start
+
+### Prerequisites
+- Node.js (v18+)
+- Python 3.10+
+- Docker (optional, for dev shell)
+
+### Installation
+```bash
+make install
+```
+
+### Development
+```bash
+# Start the dev environment (Docker)
+make dev
+
+# Or run locally
+cd server && npm run dev
+cd client && npm run dev
+```
+
+## 🤝 Contributing
+
+We follow a strict development workflow. Please read [CONTRIBUTING.md](file:///home/sinan/Documents/repositories/local/plexus/CONTRIBUTING.md) before starting.
+
+1. **Pick a Task**: Use `make task-list` to find something to work on.
+2. **Code**: Implement your changes.
+3. **Verify**: Run `make lint test` to ensure quality.
+4. **Commit**: Pre-commit hooks will automatically run linting and tests.
+5. **Document**: Update relevant docs if you add new features.
+
+---
+Built with ❤️ by the Plexus Team.
diff --git a/docs/data-model.md b/docs/data-model.md
new file mode 100644
index 0000000..482f092
--- /dev/null
+++ b/docs/data-model.md
@@ -0,0 +1,43 @@
+# 📊 Data Model
+
+Plexus uses **DuckDB** for fast, analytical, and serverless-friendly data storage.
+
+## 🗄 Tables
+
+### `users`
+Stores user identity and profile information.
+- `wallet_address` (VARCHAR, PK): Unique Solana wallet address.
+- `username` (VARCHAR, UNIQUE): Display name.
+- `bio` (VARCHAR): User biography.
+- `banner_color` (VARCHAR): Hex code for profile banner.
+- `last_seen` (TIMESTAMP): Last activity time.
+
+### `messages`
+Stores chat history.
+- `id` (INTEGER, PK): Unique message ID (from `seq_msg_id`).
+- `channel_id` (VARCHAR): ID of the channel.
+- `wallet_address` (VARCHAR, FK): Sender's wallet.
+- `content` (VARCHAR): Message text.
+- `timestamp` (TIMESTAMP): Time sent.
+- `tx_id` (VARCHAR): Simulated transaction ID.
+
+### `reactions`
+Stores message reactions.
+- `message_id` (INTEGER, FK): ID of the message.
+- `wallet_address` (VARCHAR, FK): User who reacted.
+- `emoji` (VARCHAR): The emoji character.
+- *Composite PK*: `(message_id, wallet_address, emoji)`.
+
+### `posts`
+Stores social wall posts.
+- `id` (INTEGER, PK): Unique post ID (from `seq_post_id`).
+- `wallet_address` (VARCHAR, FK): Owner of the wall.
+- `content` (VARCHAR): Post text.
+- `timestamp` (TIMESTAMP): Time posted.
+
+## 🔢 Sequences
+- `seq_msg_id`: Increments for each new message.
+- `seq_post_id`: Increments for each new wall post.
+
+## 🔄 Migrations
+The `server/db.js` file handles automatic schema initialization and migrations (e.g., adding `tx_id` or `bio` columns if they are missing from an existing database).
diff --git a/docs/functions.md b/docs/functions.md
new file mode 100644
index 0000000..1d42808
--- /dev/null
+++ b/docs/functions.md
@@ -0,0 +1,32 @@
+# ⚙️ Functions & API
+
+Plexus communicates primarily through WebSockets (Socket.io) for real-time interaction.
+
+## 🔌 Socket Events
+
+### 📥 Client to Server
+- `join({ walletAddress, username })`: Register or login a user.
+- `sendMessage({ channelId, walletAddress, content, txId })`: Send a message to a channel.
+- `toggleReaction({ messageId, walletAddress, emoji })`: Toggle a reaction on a message.
+- `updateUsername({ walletAddress, newUsername, txId })`: Change username (simulated cost).
+- `getProfile(walletAddress)`: Fetch user profile and wall posts.
+- `updateProfile({ walletAddress, bio, bannerColor })`: Update profile details.
+- `createPost({ walletAddress, content })`: Post a message to the user's wall.
+
+### 📤 Server to Client
+- `userList(users)`: Broadcast the updated list of online/offline users.
+- `newMessage(message)`: Broadcast a new message to all clients.
+- `updateReactions({ messageId, reactions })`: Broadcast updated reactions for a message.
+- `usernameUpdated({ username })`: Confirm a username change to the specific user.
+- `profileData(data)`: Send requested profile data to a user.
+- `profileUpdated(data)`: Confirm profile update.
+- `postCreated(post)`: Confirm post creation.
+- `error({ message })`: Send error messages to the client.
+
+## 🌐 REST API
+- `GET /api/channels`: List all available chat channels.
+- `GET /api/messages/:channelId`: Fetch the last 100 messages and reactions for a channel.
+
+## 🛠 Internal Logic
+- **Username Authority**: The server validates and ensures unique usernames, appending suffixes if necessary.
+- **Transaction Simulation**: The client simulates a 1.5s delay and a 5% failure rate for "blockchain" transactions.
diff --git a/docs/structure.md b/docs/structure.md
new file mode 100644
index 0000000..20cfa60
--- /dev/null
+++ b/docs/structure.md
@@ -0,0 +1,33 @@
+# 📂 Project Structure
+
+Plexus is organized into three main areas: the client, the server, and the internal tooling.
+
+## 📁 Root Directory
+- `Makefile`: Central automation script for installation, development, and tasks.
+- `docker-compose.yml`: Defines the development environment services.
+- `Dockerfile.dev`: Unified development shell with all dependencies.
+- `package.json`: Root package for devtooling (Husky, lint-staged).
+- `pyproject.toml`: Configuration for Python linting (Ruff).
+
+## 📁 `client/` (Frontend)
+Built with Vue 3 and Vite.
+- `src/components/`: Reusable UI components (Chat, Profile, UserList, etc.).
+- `src/stores/`: Pinia stores for state management (`chat.js`).
+- `src/style.css`: Global styles and Tailwind utilities.
+- `tailwind.config.js`: Custom theme and animations.
+
+## 📁 `server/` (Backend)
+Built with Node.js and Socket.io.
+- `index.js`: Main entry point, socket event handlers.
+- `db.js`: Database initialization and schema management.
+- `data/`: Contains the DuckDB database file (`chat.duckdb`).
+- `tests/`: Integration tests for socket events.
+
+## 📁 `tasks/` (Internal Tooling)
+Python-based task tracker.
+- `cli.py`: Command-line interface for managing tasks.
+- `db.py`: DuckDB backend for task storage.
+- `tasks.duckdb`: Database for internal tasks.
+
+## 📁 `docs/` (Documentation)
+Linked Markdown files covering all aspects of the project.