docs: overhaul project documentation and contributing guide (Task #190)

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).

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.

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.