docs: implement professional documentation structure and project hygiene

CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Added
+- Professional documentation structure in `docs/`.
+- Internal task tracker using Python and DuckDB.
+- Centralized `Makefile` for project automation.
+- Dockerized development shell.
+- Unique username enforcement on the server.
+- Transaction simulation for messages, reactions, and username changes.
+
+### Fixed
+- DuckDB parameter handling issue in the backend.
+- Reaction animations and persistence.
+- `.gitignore` consolidation.

CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing to Plexus
+
+Thank you for your interest in contributing to Plexus!
+
+## 🤝 How to Contribute
+
+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.
+
+## 📜 Code of Conduct
+
+Please be respectful and collaborative. We aim to build a welcoming community for all developers.

docs/README.md

@@ -0,0 +1,21 @@
+# Plexus Documentation
+
+Welcome to the official documentation for **Plexus**, a decentralized crypto chat application.
+
+## 📖 Table of Contents
+
+- [Architecture Overview](file:///home/sinan/Documents/repositories/local/plexus/docs/architecture.md) - How the system works.
+- [Development Guide](file:///home/sinan/Documents/repositories/local/plexus/docs/development.md) - Guidelines for contributors.
+- [Task Tracker](file:///home/sinan/Documents/repositories/local/plexus/docs/tasks.md) - How to use the internal task management system.
+- [Scalability & Roadmap](file:///home/sinan/Documents/repositories/local/plexus/docs/scalability.md) - Thinking bigger.
+
+## 🚀 Quick Start
+
+To get started with development, please refer to the [Development Guide](file:///home/sinan/Documents/repositories/local/plexus/docs/development.md).
+
+## 🛠 Tech Stack
+
+- **Frontend**: Vue 3, Vite, TailwindCSS, Pinia.
+- **Backend**: Node.js, Express, Socket.IO.
+- **Database**: DuckDB (for chat history and task tracking).
+- **Blockchain**: Solana (simulated transactions).

docs/architecture.md

@@ -0,0 +1,34 @@
+# Architecture Overview
+
+Plexus is designed as a real-time, decentralized-first chat application.
+
+## 🏗 System Components
+
+### 1. Frontend (Client)
+- Built with **Vue 3** and **Vite**.
+- Uses **Pinia** for state management (messages, users, channels).
+- Communicates with the backend via **Socket.IO** for real-time updates.
+- Simulates Solana transactions for messages, reactions, and username changes.
+
+### 2. Backend (Server)
+- Built with **Node.js** and **Express**.
+- Uses **Socket.IO** to handle real-time communication.
+- **DuckDB** is used as the primary data store for:
+    - User profiles (wallet addresses, unique usernames).
+    - Message history.
+    - Reactions.
+
+### 3. Database Schema
+- `users`: `wallet_address` (PK), `username` (UNIQUE), `last_seen`.
+- `messages`: `id` (PK), `channel_id`, `wallet_address`, `content`, `timestamp`, `tx_id`.
+- `reactions`: `message_id`, `wallet_address`, `emoji`.
+
+## 🔄 Data Flow
+
+1. **User Joins**: Client emits `join` with wallet address and requested username. Server verifies/generates unique username and updates `users` table.
+2. **Sending Message**: Client simulates transaction, then emits `sendMessage` with `txId`. Server saves message to DuckDB and broadcasts `newMessage` to all clients.
+3. **Reactions**: Client emits `toggleReaction`. Server updates `reactions` table and broadcasts `updateReactions`.
+
+## 🛡 Security
+- Currently uses a simple wallet-based identification.
+- Future versions will implement full message signing and verification.

docs/development.md

@@ -0,0 +1,36 @@
+# Development Guide
+
+Welcome to the Plexus development team! Please follow these guidelines to ensure a consistent and high-quality codebase.
+
+## 🛠 Setup
+
+1. **Docker**: The easiest way to develop is using the dockerized shell.
+   ```bash
+   make shell
+   ```
+2. **Local**: If you prefer local development:
+   ```bash
+   make install
+   ```
+
+## 📝 Coding Standards
+
+- **Linting**: Always run `make lint` before pushing.
+- **Testing**: Add unit or integration tests for new features. Use `make test` to run them.
+- **Documentation**: Update the `docs/` directory if you change architecture or add major features.
+
+## 🌿 Git Workflow
+
+- **Commits**: Use descriptive commit messages.
+- **Task IDs**: Always include the task ID in your commit message if applicable.
+  - Example: `feat: add emoji picker (Task #123)`
+- **Regular Commits**: Commit early and often. Small, atomic commits are preferred.
+
+## 📋 Task Management
+
+We use an internal task tracker powered by DuckDB.
+- List tasks: `make task-list`
+- Add task: `make task-add title="My new task"`
+- Complete task: `make task-done id=1`
+
+See [Task Tracker Documentation](file:///home/sinan/Documents/repositories/local/plexus/docs/tasks.md) for more details.

docs/scalability.md

@@ -0,0 +1,30 @@
+# Thinking Bigger: Scalability & Future Roadmap
+
+Plexus is currently a robust MVP, but to scale to millions of users, we need to consider several architectural improvements.
+
+## 🚀 Scalability Improvements
+
+### 1. Backend Scaling
+- **Load Balancing**: Use Nginx or HAProxy to distribute traffic across multiple Node.js instances.
+- **Redis for Pub/Sub**: Currently, Socket.IO broadcasts are limited to a single server. Integrating Redis will allow broadcasting across multiple server instances.
+- **Database Sharding**: As the message history grows, sharding DuckDB or migrating to a distributed database like CockroachDB or ClickHouse (for analytics) may be necessary.
+
+### 2. Frontend Performance
+- **Code Splitting**: Use Vite's code-splitting features to reduce initial load times.
+- **Service Workers**: Implement PWA features for offline support and push notifications.
+- **Virtual Scrolling**: For channels with thousands of messages, implement virtual scrolling to maintain UI performance.
+
+## 🛠 Advanced Tooling
+
+### 1. CI/CD Pipeline
+- **GitHub Actions**: Automate linting, testing, and deployment.
+- **Automated Testing**: Expand test coverage with Playwright for E2E testing and Vitest for unit testing.
+
+### 2. Monitoring & Logging
+- **Prometheus & Grafana**: Track server performance and user metrics.
+- **Sentry**: Real-time error tracking and reporting.
+
+## 🌐 Decentralization Roadmap
+- **IPFS Integration**: Store media files and message history on IPFS for true decentralization.
+- **Smart Contracts**: Move the $PLEXUS transaction logic to on-chain Solana programs.
+- **DAO Governance**: Implement a DAO to allow users to vote on protocol changes.

docs/tasks.md

@@ -0,0 +1,26 @@
+# Task Tracker
+
+Plexus uses a custom-built task tracking system to manage its development lifecycle. The data is stored in a local DuckDB database (`data/tasks.duckdb`).
+
+## 🛠 Commands
+
+You can interact with the task tracker using the `Makefile`:
+
+| Command | Description |
+|---------|-------------|
+| `make task-list` | List all active tasks. |
+| `make task-add title="..."` | Add a new task. |
+| `make task-update id=... status="..."` | Update a task's status. |
+| `make task-done id=...` | Mark a task as completed. |
+| `make task-filter status="..."` | Filter tasks by status. |
+
+## 📊 Task Statuses
+
+- `todo`: Task is waiting to be started.
+- `in-progress`: Task is currently being worked on.
+- `done`: Task is completed.
+- `blocked`: Task is waiting on external factors.
+
+## 🐍 Implementation Details
+
+The task tracker is implemented in Python and uses the `duckdb` library. The source code can be found in the `tasks/` directory.