docs: overhaul project documentation and contributing guide (Task #190)
This commit is contained in:
@@ -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.
|
### 1. Pick a Task
|
||||||
2. **Fork & Branch**: Create a new branch for your feature or bugfix.
|
Before coding, ensure you are working on an assigned task.
|
||||||
3. **Develop**: Follow the [Development Guide](file:///home/sinan/Documents/repositories/local/plexus/docs/development.md).
|
- List tasks: `make task-list`
|
||||||
4. **Test**: Ensure all tests pass.
|
- Add a task: `make task-add title="Your Task"`
|
||||||
5. **Pull Request**: Submit a PR with a clear description of your changes.
|
- 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!
|
||||||
|
|||||||
66
README.md
Normal file
66
README.md
Normal file
@@ -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".
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## 🚀 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.
|
||||||
43
docs/data-model.md
Normal file
43
docs/data-model.md
Normal file
@@ -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).
|
||||||
32
docs/functions.md
Normal file
32
docs/functions.md
Normal file
@@ -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.
|
||||||
33
docs/structure.md
Normal file
33
docs/structure.md
Normal file
@@ -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.
|
||||||
Reference in New Issue
Block a user