{"id":47264269,"url":"https://github.com/theacmada/gwirian","last_synced_at":"2026-03-29T08:00:52.329Z","repository":{"id":331267354,"uuid":"1031401389","full_name":"TheAcmada/gwirian","owner":"TheAcmada","description":"A modern test scenario management platform for QA engineers and managers. Create, organize, and track test scenarios with a modern BDD approach.","archived":false,"fork":false,"pushed_at":"2026-03-14T18:51:49.000Z","size":1120,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-15T05:20:56.274Z","etag":null,"topics":["quality-assurance","testing"],"latest_commit_sha":null,"homepage":"https://www.gwirian.com","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheAcmada.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-03T16:58:32.000Z","updated_at":"2026-03-14T18:51:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/TheAcmada/gwirian","commit_stats":null,"previous_names":["theacmada/gwirian"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TheAcmada/gwirian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAcmada%2Fgwirian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAcmada%2Fgwirian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAcmada%2Fgwirian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAcmada%2Fgwirian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheAcmada","download_url":"https://codeload.github.com/TheAcmada/gwirian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAcmada%2Fgwirian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31136694,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-29T07:35:32.000Z","status":"ssl_error","status_checked_at":"2026-03-29T07:30:10.597Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["quality-assurance","testing"],"created_at":"2026-03-15T03:00:23.409Z","updated_at":"2026-03-29T08:00:52.321Z","avatar_url":"https://github.com/TheAcmada.png","language":"Ruby","funding_links":[],"categories":["Open Source Rails Apps"],"sub_categories":["Articles"],"readme":"# Gwirian\n\n**A modern BDD (Behavior-Driven Development) feature management platform that helps teams collaborate, organize, and track their software features from conception to execution.**\n\nGwirian empowers development teams to manage their BDD features with ease. Create and organize features, define scenarios, track executions, and collaborate with your team—all in one beautiful, fast, and intuitive platform. Built with modern web technologies for a seamless experience.\n\n## Table of Contents\n\n- [What Gwirian Does](#what-gwirian-does)\n- [Key Features](#key-features)\n- [Architecture Overview](#architecture-overview)\n- [Technical Stack](#technical-stack)\n- [Requirements](#requirements)\n- [Quick Start](#quick-start)\n- [Development](#development)\n- [Testing](#testing)\n- [External Services](#external-services)\n- [MCP Server](#mcp-server)\n- [Deployment](#deployment)\n- [Configuration](#configuration)\n- [Resources](#resources)\n\n## What Gwirian Does\n\n### **Organize Your BDD Workflow**\nManage all your Behavior-Driven Development features in one place. Create features, define scenarios with Given/When/Then steps, and track their execution status across multiple projects. Keep your team aligned with a centralized view of your BDD specifications.\n\n### **Multi-Workspace Organization**\nOrganize your work into workspaces, each containing multiple projects. Perfect for teams managing multiple products or clients. Workspace members can have different roles (owner, admin, viewer) with fine-grained access control.\n\n### **Powerful Search \u0026 Discovery**\nFind features instantly with full-text search powered by Elasticsearch. Tag your features and scenarios for better organization and quick filtering. Never lose track of important specifications again.\n\n### **Team Collaboration**\nInvite team members to workspaces and projects with role-based access control. Manage project memberships, track who's working on what, and maintain clear ownership of features and scenarios.\n\n### **Execution Tracking**\nMonitor scenario executions to understand which features have been tested and their current status (pending, passed, failed). Keep your team informed about the progress of your BDD specifications with detailed execution history.\n\n### **Secure \u0026 Auditable**\nPasswordless magic link authentication via email. Login history tracking ensures your team's work is secure and auditable. Know who accessed what and when.\n\n### **Modern \u0026 Fast**\nExperience a lightning-fast interface built with the latest web technologies. Navigation uses **htmx** so links and shortcuts update only the main content—no full page reloads. Enjoy smooth, reactive UI with **Alpine.js**, beautiful styling with **Tailwind CSS v4**, and a **global command palette** (Ctrl+K / ⌘K) for search and quick navigation. The app is keyboard-first: use **G** then a letter for project navigation (Linear-style) and **?** to view all shortcuts.\n\n\n## Key Features\n\n- **Workspaces**: Organize teams and projects into separate workspaces\n- **Projects**: Group related features within a workspace\n- **Features**: Define BDD features with descriptions and backgrounds\n- **Scenarios**: Create scenarios with Given/When/Then structure\n- **Steps**: Define detailed steps for each scenario\n- **Executions**: Track scenario execution status and history\n- **Tags**: Organize features and scenarios with flexible tagging\n- **Search**: Full-text search powered by Elasticsearch; instant search from the global command palette (Ctrl+K)\n- **Global command palette**: One shortcut (Ctrl+K) for search, navigation, and actions—no full page reloads\n- **Keyboard-first navigation**: G-nav (G + letter) and shortcuts overlay (?); prev/next feature (G P / G N)\n- **API Access**: Workspace-scoped API tokens for programmatic access\n- **MCP Integration**: Model Context Protocol server for AI assistant integration\n\n## Architecture Overview\n\n### Data Model\n\nGwirian follows a hierarchical structure:\n\n```\nWorkspace\n  ├── Workspace Members (users with roles)\n  └── Projects\n      ├── Project Members (email-based access)\n      └── Features\n          ├── Tags\n          └── Scenarios\n              ├── Steps (Given/When/Then)\n              └── Scenario Executions\n```\n\n### Authentication\n\n- **Magic Links**: Passwordless authentication via email links (6-character code)\n- **Sessions**: Database-backed session management with expiration\n- **API Tokens**: Workspace-scoped tokens for programmatic access\n\n### Authorization\n\n- **CanCanCan**: Role-based authorization throughout the application\n- **Workspace Roles**: Owner, Admin, Viewer\n- **Project Access**: Email-based project membership with roles\n\n### Background Jobs\n\n- **Solid Queue**: Database-backed job queue (no Redis required)\n- **Solid Cache**: Database-backed caching\n- **Solid Cable**: Database-backed Action Cable\n\n## Technical Stack\n\n### Core Technologies\n\n- **Ruby 4.0.0**: Modern Ruby runtime\n- **Rails 8.0**: Latest Rails framework\n- **SQLite3**: Default database (easily switchable to PostgreSQL/MySQL)\n- **Tailwind CSS v4**: Utility-first CSS framework\n- **Alpine.js**: Lightweight JavaScript framework for interactivity\n- **htmx**: Dynamic HTML interactions without page reloads\n- **ViewComponent**: Reusable UI components\n\n### Key Gems\n\n- **Elasticsearch**: Full-text search and indexing\n- **CanCanCan**: Authorization framework\n- **acts-as-taggable-on**: Flexible tagging system\n- **acts_as_list**: Sortable list support\n- **Pagy**: Fast, efficient pagination\n- **Solid Queue/Cache/Cable**: Database-backed background jobs, caching, and WebSockets\n- **Kamal**: Zero-downtime deployment\n- **Thruster**: HTTP asset caching/compression for Puma\n\n### Development Tools\n\n- **RSpec**: Testing framework\n- **FactoryBot**: Test data generation\n- **Rubocop**: Code style enforcement\n- **Brakeman**: Security vulnerability scanner\n- **Capybara**: System testing\n\n## Requirements\n\n- **Ruby 4.0.0** (see `.ruby-version`)\n- **Docker** and **Docker Compose** (for Elasticsearch and Mailhog)\n- **Bundler** (Ruby gem manager)\n- **Node.js** (for Tailwind CSS compilation)\n\n## Quick Start\n\nGet up and running in minutes:\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/TheAcmada/gwirian.git\ncd gwirian\n\n# 2. Install dependencies\nbundle install\n\n# 3. Start external services (Elasticsearch, Mailhog)\ndocker-compose up -d\n\n# 4. Setup database\nbin/rails db:create db:migrate db:seed\n\n# 5. Reindex Elasticsearch\nbin/rails elasticsearch:reindex\n\n# 6. Start the development server\nbin/dev\n```\n\nVisit [http://localhost:3000](http://localhost:3000) and sign in with your email address. You'll receive a magic link code via email (or check the browser console/response headers in development for the code).\n\n\u003e **Note**: The development server runs both the Rails server and Tailwind CSS watcher via `Procfile.dev`. Make sure Elasticsearch is running before reindexing.\n\n## Development\n\n### Starting the Server\n\nThe `bin/dev` command starts both the Rails server and Tailwind CSS watcher:\n\n```bash\nbin/dev\n```\n\nThis uses `Procfile.dev` which runs:\n- `web`: Rails server (port 3000)\n- `css`: Tailwind CSS watcher for auto-compilation\n\n### Development Workflow\n\n- **Tailwind CSS**: Auto-compiled via `bin/rails tailwindcss:watch` (included in `bin/dev`)\n- **htmx and Alpine.js**: Included via `/public/js/htmx.min.js` and `/public/js/alpinejs.min.js`\n- **Main layout**: `app/views/layouts/application.html.erb`\n- **ViewComponent components**: Located in `app/components/`\n- **Models**: Located in `app/models/`\n- **Controllers**: Located in `app/controllers/`\n\n### Database Management\n\n```bash\n# Create database\nbin/rails db:create\n\n# Run migrations\nbin/rails db:migrate\n\n# Reset database (drop, create, migrate, seed)\nbin/rails db:reset\n\n# Load seed data\nbin/rails db:seed\n```\n\n### Elasticsearch Management\n\n```bash\n# Reindex all features and scenario executions\nbin/rails elasticsearch:reindex\n```\n\nThis task will:\n1. Delete existing Elasticsearch indices (if they exist)\n2. Create new indices with proper settings and mappings\n3. Import all features and scenario executions into the indices\n\n\u003e **Note**: Make sure Elasticsearch is running before executing this command (`docker-compose up -d`).\n\n## Testing\n\nGwirian uses both RSpec and Rails' built-in test framework:\n\n```bash\n# Run all tests\nbundle exec rspec \u0026\u0026 bin/rails test\n\n# Run only RSpec tests\nbundle exec rspec\n\n# Run only Rails tests\nbin/rails test\n\n# Run a specific test file\nbundle exec rspec spec/path/to/file_spec.rb\nbin/rails test test/path/to/file_test.rb\n\n# Run tests in parallel (if configured)\nbundle exec rspec --parallel\n```\n\n### Test Data\n\n- **FactoryBot**: Used for generating test data in RSpec\n- **Fixtures**: Used for Rails tests\n\n## External Services\n\nThis app depends on external services for full functionality, which can be launched using Docker Compose:\n\n### Services\n\n- **Elasticsearch** (port 9200): Full-text search and indexing\n  - Available at [http://localhost:9200](http://localhost:9200)\n  - Health check: `curl http://localhost:9200`\n\n- **Mailhog** (ports 8025, 1025): Local email testing\n  - Web UI: [http://localhost:8025](http://localhost:8025)\n  - SMTP: `localhost:1025`\n\n### Starting Services\n\n```bash\n# Start all services in detached mode\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f\n\n# Stop services\ndocker-compose down\n\n# Stop and remove volumes\ndocker-compose down -v\n```\n\n## MCP Server\n\nGwirian includes a **Model Context Protocol (MCP) server** that allows AI assistants and other tools to interact with your BDD features, scenarios, and executions programmatically.\n\nFor complete configuration, usage instructions, and available tools, see the [MCP Client Configuration Guide](docs/mcp.md).\n\n## Deployment\n\nGwirian uses **Kamal** for zero-downtime deployments. Kamal provides a simple, Docker-based deployment workflow that works with any hosting provider.\n\n### Prerequisites\n\n- Docker installed on your server\n- SSH access to your server\n- Domain name configured\n\n### Deployment Guide\n\nFor a complete walkthrough, see the [Kamal deployment guide](docs/kamal-deployment.md) or the [Docker deployment guide](docs/docker-deployment.md).\n\n### Quick Deploy\n\n```bash\n# Deploy to production\nbin/kamal deploy\n\n# Deploy with specific environment\nbin/kamal deploy -d production\n\n# View deployment configuration\ncat config/deploy.yml\n```\n\n### Deployment Features\n\n- Zero-downtime deployments\n- Automatic health checks\n- Rollback support\n- Environment-specific configurations\n- Elasticsearch service included in deployment\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the project root (see `.env.example` for reference):\n\n```bash\n# Database\nDATABASE_URL=sqlite3:db/development.sqlite3\n\n# Elasticsearch\nELASTICSEARCH_URL=http://localhost:9200\n\n# Application\nSECRET_KEY_BASE=your_secret_key_here\nRAILS_ENV=development\n```\n\n### Configuration Files\n\n- **Database**: `config/database.yml`\n- **Elasticsearch**: `config/initializers/elasticsearch.rb`\n- **Routes**: `config/routes.rb`\n- **Application**: `config/application.rb`\n- **Environments**: `config/environments/`\n\n## Resources\n\n### Documentation\n\n- [Ruby on Rails Guides](https://guides.rubyonrails.org/)\n- [Tailwind CSS v4 Docs](https://tailwindcss.com/docs)\n- [Alpine.js Docs](https://alpinejs.dev/start-here)\n- [htmx Docs](https://htmx.org/docs/)\n- [ViewComponent Docs](https://viewcomponent.org/)\n- [Kamal Deploy](https://kamal-deploy.org)\n- [Elasticsearch Ruby Client](https://github.com/elastic/elasticsearch-ruby)\n\n### Project Documentation\n\n- [MCP Client Configuration Guide](docs/mcp.md)\n- [Kamal Deployment Guide](docs/kamal-deployment.md)\n\n### Community\n\n- [GitHub Issues](https://github.com/TheAcmada/gwirian/issues)\n- [GitHub Discussions](https://github.com/TheAcmada/gwirian/discussions)\n\n---\n\n**Built with ❤️ for BDD teams everywhere**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheacmada%2Fgwirian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheacmada%2Fgwirian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheacmada%2Fgwirian/lists"}