diff --git a/README.md b/README.md index 9615732..8d433e6 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,35 @@ # 🧠 Brian - Your Personal Knowledge Base -Screenshot 2026-02-20 at 4 30 00β€―PM -> A play on "brain" - Brian is your intelligent knowledge repository with vector-based similarity search, beautiful graph visualization, and seamless Goose integration. Because I cannot spell 9/10 times and I make this mistake all the time now you can too! -Screenshot 2026-02-19 at 3 35 51β€―PM +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/) +[![Node.js 16+](https://img.shields.io/badge/node-16+-green.svg)](https://nodejs.org/) +[![pnpm](https://img.shields.io/badge/pnpm-8+-orange.svg)](https://pnpm.io/) -Screenshot 2026-02-19 at 3 36 05β€―PM +Brian Screenshot +> *A play on "brain" - Brian is your intelligent knowledge repository with vector-based similarity search, beautiful graph visualization, and seamless Goose integration. Because I cannot spell 9/10 times and I make this mistake all the time, now you can too!* +--- + +## πŸ“Œ Table of Contents + +- [🌟 Features](#-features) +- [πŸ—οΈ Architecture Overview](#-architecture-overview) +- [πŸš€ Quick Start](#-quick-start) +- [πŸ“– Usage](#-usage) +- [πŸ”§ Configuration](#-configuration) +- [πŸ› οΈ Development](#-development) +- [πŸ”Œ Goose MCP Tools](#-goose-mcp-tools) +- [πŸ“Š Similarity Algorithm](#-similarity-algorithm) +- [πŸ“ˆ Comparison with Alternatives](#-comparison-with-alternatives) +- [πŸ› Troubleshooting](#-troubleshooting) +- [🀝 Contributing](#-contributing) +- [πŸ“ License](#-license) +- [πŸ™ Acknowledgments](#-acknowledgments) +- [πŸ“š Documentation](#-documentation) +- [πŸ—ΊοΈ Roadmap](#-roadmap) + +--- ## ✨ Features @@ -17,14 +40,12 @@ - **πŸ”— Link Previews**: Automatic metadata extraction from URLs - **πŸ“„ Google Docs Support**: Seamless integration with Google Drive documents -Screenshot 2026-02-04 at 12 32 03β€―PM - +Knowledge Items Screenshot ### Multi-Project Knowledge Bases - **πŸ—‚οΈ Multiple Projects**: Organize knowledge into separate project spaces -Screenshot 2026-02-04 at 12 31 45β€―PM - +Project Selector Screenshot ### Graph Visualization - **πŸ•ΈοΈ Force-Directed Graph**: Interactive D3.js visualization showing connections @@ -33,7 +54,7 @@ - **🌌 Knowledge Universe**: Zoom out to see all projects as "galaxies" in a unified space - **πŸ“ Knowledge Regions**: Group related items with visual boundaries -Screenshot 2026-02-04 at 12 31 10β€―PM +Graph Visualization Screenshot ### Hierarchical Zoom (Knowledge Universe) - **πŸ”­ Multi-Scale View**: Seamlessly zoom from individual items to entire knowledge universe @@ -41,14 +62,107 @@ - **✨ Semantic Rendering**: Labels, nodes, and links adapt based on zoom level - **πŸ“Š Zoom Indicator**: Real-time display of zoom level and current semantic view - ### AI Integration - **πŸ€– Goose Integration**: Use Brian directly from Goose AI assistant via MCP - **🧭 Region Profiles**: Configure AI behavior per knowledge region - **πŸ’‘ Smart Context**: Get relevant knowledge context for any topic -Screenshot 2026-02-04 at 12 32 30β€―PM +Goose Integration Screenshot + +--- + +## πŸ—οΈ Architecture Overview + +Brian is built with a **modular architecture** separating backend, frontend, and AI integration layers: + +``` +brian/ +β”œβ”€β”€ brian/ # Backend (Python + FastAPI) +β”‚ β”œβ”€β”€ api/ # REST API routes +β”‚ β”‚ β”œβ”€β”€ items.py # Knowledge item endpoints +β”‚ β”‚ β”œβ”€β”€ projects.py # Project management endpoints +β”‚ β”‚ β”œβ”€β”€ regions.py # Region management endpoints +β”‚ β”‚ β”œβ”€β”€ connections.py # Explicit connection endpoints +β”‚ β”‚ └── search.py # Search and similarity endpoints +β”‚ β”œβ”€β”€ database/ # SQLite database layer +β”‚ β”‚ β”œβ”€β”€ migrations.py # Database migrations +β”‚ β”‚ β”œβ”€β”€ repository.py # Data access layer (CRUD operations) +β”‚ β”‚ └── schema.py # Database schema (SQLAlchemy models) +β”‚ β”œβ”€β”€ models/ # Business models +β”‚ β”‚ β”œβ”€β”€ knowledge_item.py # Knowledge item model +β”‚ β”‚ β”œβ”€β”€ project.py # Project model +β”‚ β”‚ β”œβ”€β”€ region.py # Region model +β”‚ β”‚ └── connection.py # Connection model +β”‚ └── services/ # Business logic +β”‚ β”œβ”€β”€ similarity.py # TF-IDF + cosine similarity +β”‚ β”œβ”€β”€ clustering.py # Item clustering for graph layout +β”‚ └── embedding.py # Vector embedding utilities +β”‚ +β”œβ”€β”€ brian_mcp/ # MCP Server (Goose Integration) +β”‚ β”œβ”€β”€ server.py # MCP server implementation +β”‚ └── tools/ # MCP tool definitions +β”‚ +β”œβ”€β”€ frontend/ # Frontend (React + Vite + D3.js) +β”‚ β”œβ”€β”€ public/ # Static assets +β”‚ └── src/ +β”‚ β”œβ”€β”€ components/ # React components +β”‚ β”‚ β”œβ”€β”€ SimilarityGraph.jsx # Main graph visualization (D3.js) +β”‚ β”‚ β”œβ”€β”€ ProjectSelector.jsx # Project management UI +β”‚ β”‚ β”œβ”€β”€ ProjectPill.jsx # Project indicator +β”‚ β”‚ β”œβ”€β”€ Timeline.jsx # Chronological view +β”‚ β”‚ β”œβ”€β”€ InfinitePinboard.jsx # Spatial canvas +β”‚ β”‚ β”œβ”€β”€ RegionEditDialog.jsx # Region management +β”‚ β”‚ β”œβ”€β”€ Settings.jsx # App settings +β”‚ β”‚ └── ... +β”‚ β”œβ”€β”€ contexts/ # React contexts +β”‚ β”‚ └── SettingsContext.jsx # Global settings +β”‚ β”œβ”€β”€ store/ # State management (Zustand) +β”‚ β”‚ └── useStore.js # Centralized state +β”‚ β”œβ”€β”€ lib/ # Utilities +β”‚ β”‚ β”œβ”€β”€ api.js # API client +β”‚ β”‚ β”œβ”€β”€ constants.js # App constants +β”‚ β”‚ └── utils.js # Helper functions +β”‚ β”œβ”€β”€ App.jsx # Main app component +β”‚ └── main.jsx # Entry point +β”‚ +β”œβ”€β”€ scripts/ # Helper scripts +β”‚ β”œβ”€β”€ setup.sh # One-command installation +β”‚ β”œβ”€β”€ start.sh # Start backend + frontend +β”‚ └── stop.sh # Stop all servers +β”‚ +β”œβ”€β”€ pyproject.toml # Python project config +β”œβ”€β”€ requirements.txt # Python dependencies +β”œβ”€β”€ package.json # Frontend dependencies (in frontend/) +└── README.md # This file +``` + +### Data Flow +``` +User Interaction (Web UI / Goose) + ↓ + Frontend (React) β†’ API Requests β†’ Backend (FastAPI) + ↓ + Database (SQLite) ←→ Similarity Engine (TF-IDF) + ↓ + Graph Layout (D3.js Force-Directed) + ↓ + Visual Rendering (Canvas / SVG) +``` + +### Key Technologies +| Layer | Technology | Purpose | +|-------|------------|---------| +| Backend | FastAPI | REST API server | +| Database | SQLite + SQLAlchemy | Data persistence | +| Frontend | React + Vite | UI framework | +| Graph Visualization | D3.js | Interactive graph rendering | +| State Management | Zustand | Client-side state | +| AI Integration | MCP (Model Context Protocol) | Goose AI assistant integration | +| Styling | Tailwind CSS + shadcn/ui | UI components | +| Icons | Lucide | Icon library | +| Animations | Framer Motion | Smooth transitions | +--- ## πŸš€ Quick Start @@ -57,25 +171,26 @@ - **Python 3.8+** - [Download](https://www.python.org/downloads/) - **Node.js 16+** - [Download](https://nodejs.org/) - **pnpm** - [Install](https://pnpm.io/installation) (`npm install -g pnpm`) -- **Goose** (optional) - For AI assistant integration - https://github.com/block/goose +- **Goose** (optional) - For AI assistant integration - [https://github.com/block/goose](https://github.com/block/goose) ### One-Command Installation ```bash # Clone the repository -git clone https://github.com/yourusername/brian.git +git clone https://github.com/spencrmartin/brian.git cd brian # Run the setup script +chmod +x setup.sh ./setup.sh ``` That's it! The setup script will: -- βœ… Install all Python dependencies +- βœ… Install all Python dependencies in a virtual environment - βœ… Install all frontend dependencies -- βœ… Create the Brian data directory -- βœ… Configure the Goose extension automatically -- βœ… Create convenient start/stop scripts +- βœ… Create the Brian data directory at `~/.brian/` +- βœ… Configure the Goose extension (if Goose is installed) +- βœ… Create convenient `start.sh` and `stop.sh` scripts ### Start Brian @@ -83,9 +198,9 @@ That's it! The setup script will: ./start.sh ``` -This starts both the backend (port 8080) and frontend (port 5173) servers. - -Open your browser to: **http://localhost:5173** +This starts both servers: +- **Backend**: http://localhost:8080 +- **Frontend**: http://localhost:5173 ### Stop Brian @@ -93,15 +208,17 @@ Open your browser to: **http://localhost:5173** ./stop.sh ``` +--- + ## πŸ“– Usage ### Adding Knowledge Items **Via Web UI:** -1. Open http://localhost:5173 +1. Open [http://localhost:5173](http://localhost:5173) 2. Click the "+" button -3. Choose item type (link, note, snippet, paper) -4. Fill in the details and add tags +3. Choose item type: **Link**, **Note**, **Snippet**, or **Paper** +4. Fill in the details (title, content, URL, tags) 5. Save! **Via Goose:** @@ -113,14 +230,14 @@ Goose: βœ“ Added to your knowledge base! ### Managing Projects **Creating a Project:** -1. Click the Project Selector at the top center -2. Click "New Project" +1. Click the **Project Selector** at the top center +2. Click **"New Project"** 3. Enter name, description, choose an icon and color -4. Click Create +4. Click **Create** **Switching Projects:** - Click the Project Selector and choose a project -- Select "All Projects" to view everything across all knowledge bases +- Select **"All Projects"** to view everything across all knowledge bases **Editing Projects:** - Hover over a project in the selector and click the edit (pencil) icon @@ -128,39 +245,45 @@ Goose: βœ“ Added to your knowledge base! ### Graph Visualization -The graph view shows connections between items based on content similarity: +The graph view shows connections between items based on **content similarity**: -- **Node Colors**: Blue (links), Green (notes), Amber (snippets), Purple (papers) -- **Line Thickness**: Indicates similarity strength -- **Theme Highlighting**: Hover over tags to see themed connections +- **Node Colors**: + - πŸ”΅ Blue = Links + - 🟒 Green = Notes + - 🟑 Amber = Snippets + - 🟣 Purple = Papers +- **Line Thickness**: Indicates similarity strength (thicker = more similar) +- **Theme Highlighting**: Hover over tags to see themed connections with colored drop shadows - **Node Details**: Click any node to see full details in a bottom sheet - **Zoom & Pan**: Scroll to zoom, drag to pan - **Drag Nodes**: Reposition nodes by dragging ### Knowledge Universe (Hierarchical Zoom) -When viewing "All Projects", you can explore your entire knowledge universe: +When viewing **"All Projects"**, explore your entire knowledge universe: -1. **Zoom Out** (scale < 0.3): See all projects as distinct clusters with hull boundaries -2. **Mid Zoom** (scale 0.3-0.5): See knowledge regions within projects -3. **Zoom In** (scale > 0.5): See individual items with full labels +| Zoom Level | Scale Range | View | +|------------|-------------|------| +| **Universe** | < 0.3 | All projects as distinct "galaxies" with hull boundaries | +| **Regions** | 0.3 - 0.5 | Knowledge regions within projects | +| **Items** | > 0.5 | Individual items with full labels | -The zoom indicator in the bottom-left shows your current zoom level and semantic view. +The **zoom indicator** in the bottom-left shows your current zoom level and semantic view. ### Knowledge Regions Regions help organize related items within a project: -1. Click the Regions button in the toolbar +1. Click the **Regions** button in the toolbar 2. Create a new region with a name and color 3. Add items to regions by selecting them in the graph -4. Regions appear as visual boundaries in the graph view +4. Regions appear as **visual boundaries** in the graph view ### Searching **Via Web UI:** - Use the search bar at the top -- Results show both exact matches and similar items +- Results show both **exact matches** and **similar items** - Filter by type, tags, or project **Via Goose:** @@ -169,6 +292,8 @@ You: Search Brian for "machine learning" Goose: Found 5 items related to machine learning... ``` +--- + ## πŸ”§ Configuration ### Environment Variables @@ -212,6 +337,8 @@ extensions: **After setup, restart Goose to load the Brian extension.** +--- + ## πŸ› οΈ Development ### Manual Setup @@ -221,7 +348,7 @@ If you prefer manual installation: ```bash # Backend setup python3 -m venv venv -source venv/bin/activate +source venv/bin/activate # On Windows: venv\Scripts\activate pip install -e . # Frontend setup @@ -288,228 +415,119 @@ python test_mcp_simple.py python test_search_fix.py ``` -## 🎨 UI Features - -### Project Selector -- Large pill-shaped button at top center -- Shows current project with icon, name, and item count -- "All Projects" mode shows universe icon with total counts -- Dropdown with all projects, create new, and edit options -- 25+ Lucide icons to choose from - -### Timeline View -- Chronological display of all items -- Grouped by date -- Project pills showing item origin -- Theme lines connecting related items -- Smooth animations - -### Graph View -- Force-directed layout with D3.js -- Real-time similarity calculations -- Interactive node selection -- Theme-based filtering with drop shadows -- Bottom sheet for detailed view with project pills -- Pulsing animation on selected nodes -- **Hierarchical zoom** with semantic rendering -- **Project hulls** when viewing all projects -- **Zoom indicator** showing current level - -### Navigation -- Circular icon buttons matching modern UI patterns -- Smooth transitions between views -- Responsive design -- Keyboard shortcuts (coming soon) +--- ## πŸ”Œ Goose MCP Tools -When integrated with Goose, Brian provides these tools: +When integrated with Goose, Brian provides the following tools: ### Knowledge Management -#### `create_knowledge_item` -Add new items to your knowledge base. -``` -Parameters: -- title: Item title -- content: Main content -- item_type: link, note, snippet, or paper -- url: Optional URL -- tags: Optional list of tags -- project_id: Optional project to add to -``` - -#### `search_knowledge` -Search your knowledge base with full-text and similarity search. -``` -Parameters: -- query: Search query -- limit: Max results (default: 10) -- project_id: Optional project filter -``` - -#### `find_similar_items` -Find items similar to a given item. -``` -Parameters: -- item_id: UUID of the reference item -- limit: Max results (default: 5) -``` - -#### `get_item_details` -Get full details of a specific item. -``` -Parameters: -- item_id: UUID of the item -``` - -#### `update_knowledge_item` -Update an existing knowledge item's content, tags, or other properties. -``` -Parameters: -- item_id: UUID of the item to update -- title: Optional new title -- content: Optional new content -- tags: Optional new tags list -- url: Optional new URL -``` - -#### `delete_knowledge_item` -Delete a knowledge item from the database. This action cannot be undone. -``` -Parameters: -- item_id: UUID of the item to delete -``` +| Tool | Description | Parameters | +|------|-------------|------------| +| `create_knowledge_item` | Add new items to your knowledge base | `title`, `content`, `item_type`, `url`, `tags`, `project_id` | +| `search_knowledge` | Search with full-text and similarity | `query`, `limit`, `project_id` | +| `find_similar_items` | Find items similar to a given item | `item_id`, `limit` | +| `get_item_details` | Get full details of a specific item | `item_id` | +| `update_knowledge_item` | Update an existing item | `item_id`, `title`, `content`, `tags`, `url` | +| `delete_knowledge_item` | Delete an item (cannot be undone) | `item_id` | ### Project Management -#### `list_projects` -List all knowledge base projects. - -#### `create_project` -Create a new knowledge base project. -``` -Parameters: -- name: Project name -- description: Optional description -- icon: Optional emoji icon -- color: Optional hex color -``` - -#### `switch_project` -Switch the default project for new items. -``` -Parameters: -- project_id: UUID of the project -``` - -#### `get_project_context` -Get knowledge context from a specific project. -``` -Parameters: -- project_id: Optional project ID -- query: Optional query to filter items -- limit: Max items (default: 20) -``` +| Tool | Description | Parameters | +|------|-------------|------------| +| `list_projects` | List all knowledge base projects | - | +| `create_project` | Create a new project | `name`, `description`, `icon`, `color` | +| `switch_project` | Switch default project for new items | `project_id` | +| `get_project_context` | Get context from a specific project | `project_id`, `query`, `limit` | ### Region Management -#### `list_regions` -List all knowledge regions. +| Tool | Description | Parameters | +|------|-------------|------------| +| `list_regions` | List all knowledge regions | - | +| `create_region` | Create a new region | `name`, `description`, `color`, `item_ids` | +| `get_region_context` | Get context from a specific region | `region_id`, `query` | -#### `create_region` -Create a new knowledge region. -``` -Parameters: -- name: Region name -- description: Optional description -- color: Optional hex color -- item_ids: Optional items to include -``` +### Context & Intelligence -#### `get_region_context` -Get knowledge context from a specific region. -``` -Parameters: -- region_id: UUID of the region -- query: Optional query to filter items -``` +| Tool | Description | Parameters | +|------|-------------|------------| +| `get_knowledge_context` | Get relevant items for a topic | `topic`, `limit` | +| `suggest_regions` | Suggest relevant regions for a query | `query`, `limit` | +| `debug_item_connections` | Debug similarity connections | `item_id` | -### Context & Intelligence +### Connection Management -#### `get_knowledge_context` -Get relevant knowledge items for a topic. -``` -Parameters: -- topic: Topic to get context for -- limit: Max items (default: 5) -``` +| Tool | Description | Parameters | +|------|-------------|------------| +| `create_connection` | Create explicit connection between items | `source_item_id`, `target_item_id`, `connection_type`, `strength`, `notes` | +| `get_item_connections` | Get all connections for an item | `item_id` | +| `update_connection` | Update an existing connection | `connection_id`, `connection_type`, `strength`, `notes` | +| `delete_connection` | Delete a connection | `connection_id` | -#### `suggest_regions` -Suggest relevant regions for a query. -``` -Parameters: -- query: Query to find relevant regions -- limit: Max regions (default: 3) -``` +--- -#### `debug_item_connections` -Debug similarity connections for an item. -``` -Parameters: -- item_id: UUID of the item to debug -``` +## πŸ“Š Similarity Algorithm -### Connection Management +Brian uses a **hybrid approach** for finding connections between knowledge items: -Explicit connections between knowledge items for the graph and relationship tracking. +1. **TF-IDF Vectorization**: Converts text content to numerical vectors + - Term Frequency (TF): How often a word appears in a document + - Inverse Document Frequency (IDF): How important a word is across all documents -#### `create_connection` -Create an explicit connection between two items. -``` -Parameters: -- source_item_id: UUID of the source item -- target_item_id: UUID of the target item -- connection_type: Optional - related, references, extracted_from, inspired_by, etc. -- strength: Optional - 0.0 to 1.0 (default: 1.0) -- notes: Optional notes about the connection -``` +2. **Cosine Similarity**: Measures the angle between vectors + - Range: `-1` (opposite) to `1` (identical) + - Brian uses values from `0` to `1` -#### `get_item_connections` -Get all explicit connections for an item. -``` -Parameters: -- item_id: UUID of the item -``` +3. **Threshold Filtering**: Only shows connections above **0.15 similarity** + - Adjustable via configuration -#### `update_connection` -Update an existing connection. -``` -Parameters: -- connection_id: ID of the connection to update -- connection_type: Optional new type -- strength: Optional new strength 0.0-1.0 -- notes: Optional new notes -``` +4. **Global IDF Scores**: Pre-computed for all documents for efficiency -#### `delete_connection` -Delete an explicit connection between items. -``` -Parameters: -- connection_id: ID of the connection to delete -``` +5. **Project-Aware**: Can filter connections by project -## πŸ“Š Similarity Algorithm +### Algorithm Workflow +``` +Input: All knowledge items + ↓ +1. Preprocess text (tokenize, lowercase, remove stopwords) + ↓ +2. Build TF-IDF matrix for all documents + ↓ +3. Compute cosine similarity between all pairs + ↓ +4. Filter by threshold (default: > 0.15) + ↓ +5. Return top-N similar items for each item +``` + +### Performance +- **Time Complexity**: O(nΒ²) for similarity matrix (n = number of items) +- **Space Complexity**: O(n * m) where m = vocabulary size +- **Optimizations**: + - Cached TF-IDF vectors + - Lazy similarity computation + - Project-based filtering -Brian uses a hybrid approach for finding connections: +--- -1. **TF-IDF Vectorization**: Converts text to numerical vectors -2. **Cosine Similarity**: Measures angle between vectors -3. **Threshold Filtering**: Only shows connections above 0.15 similarity -4. **Global IDF Scores**: Pre-computed for all documents -5. **Project-Aware**: Can filter connections by project +## πŸ“ˆ Comparison with Alternatives + +| Feature | Brian | Obsidian | Logseq | Roam Research | Notion | +|---------|-------|----------|--------|----------------|--------| +| **Local-First** | βœ… Yes | βœ… Yes | βœ… Yes | ❌ No | ❌ No | +| **Graph Visualization** | βœ… Yes (D3.js) | βœ… Yes (Plugins) | βœ… Yes | βœ… Yes | ❌ No | +| **Vector Search** | βœ… Yes (TF-IDF) | ❌ No | ❌ No | ❌ No | ❌ No | +| **AI Integration** | βœ… Yes (Goose MCP) | ❌ No | ❌ No | ❌ No | βœ… Yes | +| **Multi-Project** | βœ… Yes | βœ… Yes (Vaults) | βœ… Yes | βœ… Yes | βœ… Yes | +| **Open Source** | βœ… Yes | βœ… Yes | βœ… Yes | ❌ No | ❌ No | +| **Self-Hosted** | βœ… Yes | βœ… Yes | βœ… Yes | ❌ No | ❌ No | +| **Real-Time Collaboration** | ❌ No | ❌ No | ❌ No | βœ… Yes | βœ… Yes | +| **Mobile App** | ❌ No | βœ… Yes | βœ… Yes | βœ… Yes | βœ… Yes | +| **Plugin Ecosystem** | ❌ No | βœ… Yes | βœ… Yes | βœ… Yes | βœ… Yes | -This creates meaningful connections between related items without manual linking. +--- ## πŸ› Troubleshooting @@ -553,26 +571,70 @@ ls -la ~/.brian/brian.db # Reset database (WARNING: deletes all data) rm ~/.brian/brian.db # Restart backend to recreate +./stop.sh +./start.sh ``` ### Graph not showing project hulls -- Ensure you're in "All Projects" mode (click Project Selector β†’ All Projects) +- Ensure you're in **"All Projects"** mode (click Project Selector β†’ All Projects) - Zoom out significantly (scale < 0.4) to see project boundaries - Check that you have items in multiple projects +--- + ## 🀝 Contributing -Contributions are welcome! Please feel free to submit a Pull Request. +Contributions are welcome! Here's how you can help: +### Getting Started 1. Fork the repository -2. Create your feature branch (`git checkout -b feature/AmazingFeature`) -3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) -4. Push to the branch (`git push origin feature/AmazingFeature`) -5. Open a Pull Request +2. Clone your fork: + ```bash + git clone https://github.com/yourusername/brian.git + cd brian + ``` +3. Create a feature branch: + ```bash + git checkout -b feature/amazing-feature + ``` +4. Make your changes and commit them: + ```bash + git commit -m 'Add some amazing feature' + ``` +5. Push to the branch: + ```bash + git push origin feature/amazing-feature + ``` +6. Open a Pull Request + +### Contribution Guidelines +- Follow the existing code style (PEP 8 for Python, ESLint for JavaScript) +- Add tests for new features +- Update documentation as needed +- Keep commits atomic and well-described +- Reference any related issues in your PR description + +### Development Workflow +```mermaid +graph TD + A[Fork Repository] --> B[Clone Locally] + B --> C[Create Feature Branch] + C --> D[Make Changes] + D --> E[Write Tests] + E --> F[Commit Changes] + F --> G[Push to Fork] + G --> H[Open Pull Request] + H --> I[Address Review Feedback] + I --> H +``` + +--- ## πŸ“ License -This project is licensed under the MIT License - see the LICENSE file for details. +This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details. + +--- ## πŸ™ Acknowledgments @@ -585,14 +647,19 @@ This project is licensed under the MIT License - see the LICENSE file for detail - Animations with [Framer Motion](https://www.framer.com/motion/) - Goose integration via [MCP](https://modelcontextprotocol.io/) +--- + ## πŸ“š Documentation - [Quick Start Guide](QUICKSTART.md) +- [Installation Guide](INSTALL.md) - [Commands Reference](COMMANDS.md) - [Google Drive Integration](GOOGLE_DRIVE_INTEGRATION.md) - [Graph Visualization Guide](GRAPH_VISUALIZATION_EXPLAINED.md) - [Theme Filtering](THEME_FILTERING.md) +--- + ## πŸ—ΊοΈ Roadmap ### Recently Completed @@ -602,7 +669,7 @@ This project is licensed under the MIT License - see the LICENSE file for detail - βœ… Project hulls and semantic zoom - βœ… All Projects view - βœ… Project pills in Timeline and Graph -- βœ… Dynamic port configuration (VITE_PORT, VITE_API_URL env vars) +- βœ… Dynamic port configuration (`VITE_PORT`, `VITE_API_URL` env vars) - βœ… Automatic project assignment for new regions - βœ… Fixed Universe Mode initial load issues - βœ… Fixed region persistence across project views