{"id":43614605,"url":"https://github.com/pyrex41/vel_tutor","last_synced_at":"2026-02-04T12:23:45.206Z","repository":{"id":322371967,"uuid":"1089180637","full_name":"pyrex41/vel_tutor","owner":"pyrex41","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-19T16:27:51.000Z","size":38977,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-19T18:14:56.742Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pyrex41.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-04T01:56:53.000Z","updated_at":"2025-11-19T16:27:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pyrex41/vel_tutor","commit_stats":null,"previous_names":["pyrex41/vel_tutor"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pyrex41/vel_tutor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fvel_tutor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fvel_tutor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fvel_tutor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fvel_tutor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pyrex41","download_url":"https://codeload.github.com/pyrex41/vel_tutor/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrex41%2Fvel_tutor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29084187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-04T03:31:03.593Z","status":"ssl_error","status_checked_at":"2026-02-04T03:29:50.742Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":[],"created_at":"2026-02-04T12:23:44.259Z","updated_at":"2026-02-04T12:23:45.201Z","avatar_url":"https://github.com/pyrex41.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vel Tutor - AI-Powered Tutoring Platform\n\n## Overview\n\nVel Tutor is an innovative AI-driven tutoring platform built with Elixir and Phoenix. The system leverages advanced AI agents, real-time collaboration features, and a modular architecture to provide personalized learning experiences. Key components include multi-agent orchestration, viral engagement mechanics, and comprehensive analytics for educational outcomes.\n\n## Architecture\n\n### Core Components\n\n- **Viral Engine**: Handles user engagement, gamification, and viral growth mechanics\n- **AI Agents**: Specialized agents for different tutoring roles (analyst, architect, developer, etc.)\n- **Real-time Features**: Phoenix Channels for live sessions and collaborative learning\n- **Task Management**: Integrated Task Master AI for workflow orchestration\n- **Analytics \u0026 Metrics**: Comprehensive tracking of learning progress and engagement\n\n### Technology Stack\n\n- **Backend**: Elixir 1.15+, Phoenix 1.7+\n- **Database**: PostgreSQL with Ecto ORM\n- **Real-time**: Phoenix Channels with Phoenix LiveView\n- **AI Integration**: Multi-model support (Claude, GPT, Gemini, etc.)\n- **Task Orchestration**: Task Master AI with MCP integration\n- **Deployment**: Fly.io with multi-region support\n\n## Project Structure\n\n```\nvel_tutor/\n├── config/                 # Phoenix configuration files\n├── docs/                   # Architecture docs and API contracts\n│   ├── stories/           # Implementation stories and context\n│   ├── api-contracts-main.md\n│   └── architecture.md\n├── lib/                    # Core application code\n│   ├── viral_engine/      # Main business logic\n│   │   ├── accounts/      # User management\n│   │   ├── agents/        # AI agent implementations\n│   │   ├── integration/   # External service integrations\n│   │   └── workers/       # Background job workers\n│   └── viral_engine_web/  # Phoenix web layer\n│       ├── controllers/   # HTTP controllers\n│       ├── live/          # LiveView components\n│       └── channels/      # Real-time channels\n├── bmad/                   # AI Agent Management System\n│   ├── bmm/              # Business Management Module\n│   ├── core/             # Core agent functionality\n│   └── docs/             # Agent documentation\n├── .taskmaster/           # Task Master AI configuration\n├── .claude/               # Claude Code integration\n├── test/                  # Elixir test suite\n├── tests/e2e/             # Playwright E2E tests\n│   ├── learning/         # Learning feature tests\n│   ├── social/           # Social feature tests\n│   └── utils/            # Test utilities and helpers\n├── TEST_PLAN.md           # E2E testing strategy and roadmap\n└── priv/                  # Database migrations and static assets\n```\n\n## Getting Started\n\n### Prerequisites\n\n- Elixir 1.15+\n- Erlang/OTP 26+\n- PostgreSQL 13+\n- Node.js 18+ (for assets)\n- Git\n\n### Installation\n\n1. **Clone the repository**\n```bash\ngit clone \u003crepository-url\u003e\ncd vel_tutor\n```\n\n2. **Install dependencies**\n```bash\n# Install Elixir dependencies\nmix deps.get\n\n# Install Node.js dependencies\ncd assets \u0026\u0026 npm install \u0026\u0026 cd ..\n\n# Copy configuration\ncp config/runtime.exs.example config/runtime.exs\ncp .env.example .env\n```\n\n3. **Configure environment**\nEdit `.env` with your database credentials and API keys:\n```bash\n# Database\nDATABASE_URL=postgresql://username:password@localhost/vel_tutor_dev\n\n# AI API Keys (at least one required)\nANTHROPIC_API_KEY=your_claude_key\nOPENAI_API_KEY=your_openai_key\nGOOGLE_API_KEY=your_gemini_key\n\n# Task Master AI (optional but recommended)\nPERPLEXITY_API_KEY=your_perplexity_key\n```\n\n4. **Set up database**\n```bash\n# Create and migrate database\nmix ecto.create\nmix ecto.migrate\n\n# Seed initial data (optional)\nmix run priv/repo/seeds.exs\n```\n\n5. **Compile and start**\n```bash\n# Compile the application\nmix compile\n\n# Start the Phoenix server\nmix phx.server\n```\n\nThe application will be available at `http://localhost:4000`.\n\n## Development Workflow\n\n### Task Management with Task Master AI\n\nThis project uses Task Master AI for structured development workflows:\n\n1. **Initialize Task Master**\n```bash\ntask-master init\n```\n\n2. **Parse Product Requirements**\nCreate a PRD in `.taskmaster/docs/prd.txt` and parse it:\n```bash\ntask-master parse-prd .taskmaster/docs/prd.txt\n```\n\n3. **Analyze and Expand Tasks**\n```bash\n# Analyze task complexity\ntask-master analyze-complexity --research\n\n# Expand complex tasks into subtasks\ntask-master expand --all --research\n```\n\n4. **Daily Development Loop**\n```bash\n# Find next task\ntask-master next\n\n# View task details\ntask-master show \u003ctask-id\u003e\n\n# Update task progress\ntask-master update-subtask --id=\u003cid\u003e --prompt=\"implementation notes...\"\n\n# Complete tasks\ntask-master set-status --id=\u003cid\u003e --status=done\n```\n\n### AI Agent Integration\n\nThe project includes BMAD (Business Management AI Development) system with specialized agents:\n\n- **BMM Agents**: Business-focused agents for analysis, planning, and UX design\n- **Core Agents**: Development and orchestration agents\n- **Workflow Agents**: Automated task execution and validation\n\nConfigure AI models:\n```bash\ntask-master models --setup\n```\n\n### Multi-Claude Development\n\nFor parallel development, use Git worktrees:\n\n```bash\n# Create worktrees for different features\ngit worktree add ../vel_tutor-auth feature/auth-system\ngit worktree add ../vel_tutor-frontend feature/liveview-components\n\n# Run Claude Code in each worktree\ncd ../vel_tutor-auth \u0026\u0026 claude\ncd ../vel_tutor-frontend \u0026\u0026 claude\n```\n\n## Key Features\n\n### 1. AI-Powered Tutoring\n\n- **Multi-Agent System**: Specialized AI agents for different tutoring roles\n- **Real-time Sessions**: Live collaborative learning sessions\n- **Personalized Learning Paths**: Adaptive content based on student progress\n- **Progress Analytics**: Detailed learning metrics and improvement tracking\n\n### 2. Viral Engagement Mechanics\n\n- **Social Learning**: Group study sessions and peer collaboration\n- **Gamification**: Achievement badges and progress milestones\n- **Referral System**: Viral growth through student invitations\n- **Challenge System**: Competitive learning challenges\n\n### 3. Real-time Collaboration\n\n- **Live Sessions**: Real-time tutoring with multiple participants\n- **Shared Whiteboards**: Collaborative problem-solving\n- **Instant Feedback**: AI-powered real-time assessment\n- **Presence Detection**: Live user status and availability\n\n### 4. Developer Experience\n\n- **Task Master AI**: Automated task management and workflow orchestration\n- **MCP Integration**: Seamless AI tool integration\n- **Multi-model Support**: Flexible AI provider configuration\n- **Comprehensive Testing**: Full Elixir test suite + Playwright E2E testing with 50+ test cases covering all major features\n\n## Configuration\n\n### Database Configuration\n\nUpdate `config/runtime.exs` for production:\n\n```elixir\nconfig :viral_engine, ViralEngine.Repo,\n  url: System.get_env(\"DATABASE_URL\"),\n  pool_size: String.to_integer(System.get_env(\"POOL_SIZE\") || \"10\")\n```\n\n### AI Model Configuration\n\nConfigure via Task Master AI:\n\n```bash\n# Set primary model (recommended: Claude 3.5 Sonnet)\ntask-master models --set-main claude-3-5-sonnet-20241022\n\n# Set research model (recommended: Perplexity)\ntask-master models --set-research perplexity-llama-3.1-sonar-large-128k-online\n\n# Set fallback model\ntask-master models --set-fallback gpt-4o-mini\n```\n\n### Feature Flags\n\nEnvironment-based feature toggles in `config/runtime.exs`:\n\n```elixir\nconfig :viral_engine, :features,\n  ai_tutoring: true,\n  viral_sharing: true,\n  real_time_collaboration: true,\n  analytics_dashboard: true\n```\n\n## Deployment\n\n### Fly.io Deployment\n\n1. **Install Fly CLI**\n```bash\ncurl -L https://fly.io/install.sh | sh\nfly auth login\n```\n\n2. **Configure Fly**\n```bash\n# Generate fly.toml (if not present)\nfly launch\n\n# Configure secrets\nfly secrets set ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY\nfly secrets set DATABASE_URL=$DATABASE_URL\n```\n\n3. **Deploy**\n```bash\nfly deploy\n```\n\n### Docker Deployment\n\nBuild and run with Docker:\n\n```dockerfile\n# Dockerfile\nFROM elixir:1.15\n\nWORKDIR /app\nCOPY . .\n\nRUN mix deps.get\nRUN mix compile\n\nEXPOSE 4000\nCMD [\"mix\", \"phx.server\"]\n```\n\n```bash\n# Build and run\ndocker build -t vel_tutor .\ndocker run -p 4000:4000 -e DATABASE_URL=... vel_tutor\n```\n\n## Testing\n\n### Unit and Integration Tests\n\n```bash\n# Run test suite\nmix test\n\n# Run specific test file\nmix test test/viral_engine/agents/\n\n# Run tests with coverage\nmix coveralls.html\n```\n\n### Load Testing\n\nK6 load tests are included:\n\n```bash\n# Basic load test\nk6 run test/load/k6-basic-load.js\n\n# Stress test\nk6 run test/load/k6-stress-test.js\n```\n\n### End-to-End Testing\n\nComprehensive Playwright E2E test suite covering all major features:\n\n```bash\n# Run full E2E test suite\nnpm run test:e2e\n\n# Run specific test categories\nnpx playwright test tests/e2e/learning/     # Learning features\nnpx playwright test tests/e2e/social/       # Social features\nnpx playwright test tests/e2e/auth.spec.ts  # Authentication\n\n# Run tests with UI mode\nnpx playwright test --ui\n\n# Generate test report\nnpx playwright show-report\n```\n\n**Test Coverage:**\n- **Learning Features**: Practice sessions, diagnostics, flashcards\n- **Social Features**: Leaderboards, badges, rewards, activity feed, viral sharing, presence\n- **Cross-cutting**: Mobile responsiveness, accessibility, performance, error handling\n- **Real-time Features**: LiveView updates, presence indicators, activity feeds\n\n**Test Infrastructure:**\n- Enhanced test helpers with LiveView support\n- Performance monitoring and accessibility checks\n- Mobile responsiveness testing\n- Comprehensive test data seeding\n\n## AI Agent System (BMAD)\n\n### Agent Roles\n\nThe BMAD system includes specialized AI agents:\n\n1. **BMM Analyst**: Requirements analysis and business logic validation\n2. **BMM Architect**: System design and architecture decisions\n3. **BMM Developer**: Code implementation and refactoring\n4. **BMM UX Designer**: User experience and interface design\n5. **BMM PM**: Project management and task orchestration\n6. **Core Agents**: Cross-cutting concerns and orchestration\n\n### Agent Workflows\n\nAgents operate through structured workflows defined in `bmad/workflows/`:\n\n- **Daily Standup**: Automated progress reporting\n- **Code Review**: Automated pull request analysis\n- **Task Planning**: Intelligent task decomposition\n- **Documentation**: Auto-generated docs and API references\n\n### Agent Configuration\n\nConfigure agent behavior in `bmad/_cfg/agents/`:\n\n```yaml\n# bmad/_cfg/agents/analyst.yaml\nrole: analyst\nmodel: claude-3-5-sonnet-20241022\ncontext_window: 128000\nspecialization:\n  - business_requirements\n  - user_stories\n  - acceptance_criteria\n```\n\n## Task Master AI Integration\n\n### Core Workflow\n\nTask Master AI manages the development workflow:\n\n1. **PRD Parsing**: Convert requirements documents to actionable tasks\n2. **Complexity Analysis**: Identify tasks needing decomposition\n3. **Task Expansion**: Break complex tasks into manageable subtasks\n4. **Dependency Management**: Track task relationships and prerequisites\n5. **Progress Tracking**: Automated status updates and completion validation\n\n### Key Commands\n\n```bash\n# Project setup\ntask-master init\ntask-master parse-prd .taskmaster/docs/prd.txt\n\n# Daily workflow\ntask-master next                    # Get next task\ntask-master show 1.2               # View task details\ntask-master update-subtask --id=1.2 --prompt=\"...\"  # Log progress\n\n# Task management\ntask-master expand --id=1 --research  # Create subtasks\ntask-master set-status --id=1.2 --status=done  # Mark complete\n\n# Analysis\ntask-master analyze-complexity --research\ntask-master complexity-report\n```\n\n### MCP Integration\n\nTask Master exposes an MCP server for Claude Code integration:\n\n1. **Configure MCP** in `.mcp.json`\n2. **Enable tools** in `.claude/settings.json`\n3. **Use slash commands** for common workflows\n\n## Monitoring and Analytics\n\n### Built-in Metrics\n\n- **Learning Analytics**: Student progress and engagement metrics\n- **System Health**: Application performance and error rates\n- **AI Usage**: Model performance and cost tracking\n- **Viral Metrics**: User acquisition and retention\n\n### External Monitoring\n\nConfigure in `config/runtime.exs`:\n\n```elixir\n# Sentry for error tracking\nconfig :sentry,\n  dsn: System.get_env(\"SENTRY_DSN\"),\n  environment_name: Mix.env()\n\n# Prometheus metrics\nconfig :prom_ex,\n  grafana: :disabled,\n  dashboard_path: \"/metrics/dashboards\",\n  plugins: [\n    PromEx.Plugins.Application,\n    PromEx.Plugins.Beam,\n    {PromEx.Plugins.Phoenix, router: ViralEngineWeb.Router},\n    PromEx.Plugins.Prometheus\n  ]\n```\n\n## Contributing\n\n### Development Guidelines\n\n1. **Follow Task Master workflow** for all features\n2. **Use feature branches**: `git checkout -b feature/task-id-description`\n3. **Write comprehensive tests** for all changes\n4. **Update documentation** in `docs/` and `bmad/docs/`\n5. **Use conventional commits**:\n   ```\n   feat: add user authentication (task 1.2)\n   fix: resolve race condition in live sessions (task 2.3)\n   docs: update API documentation (task 3.1)\n   ```\n\n### Code Style\n\n- Follow Elixir style guidelines\n- Use `mix format` before committing\n- Write comprehensive type specs\n- Add Dialyzer annotations for complex functions\n\n### Pull Request Template\n\n1. **Reference Task Master ID**: Include task ID in title and description\n2. **Test Results**: Include test coverage and load test results\n3. **Documentation**: Confirm docs are updated\n4. **AI Review**: Include BMAD agent review results\n\n## Security\n\n### Authentication \u0026 Authorization\n\n- JWT-based authentication with refresh tokens\n- Role-based access control (RBAC)\n- Rate limiting on all endpoints\n- CSRF protection enabled\n\n### Data Protection\n\n- Passwords hashed with Argon2\n- Sensitive data encrypted at rest\n- GDPR-compliant data handling\n- Audit logging for all user actions\n\n### Security Headers\n\nConfigured in `lib/viral_engine_web/endpoint.ex`:\n\n```elixir\nplug CORSPlug, origin: [\"https://app.veltutor.com\"]\nplug :put_secure_browser_headers,\n  %{\n    \"x-frame-options\" =\u003e \"SAMEORIGIN\",\n    \"x-xss-protection\" =\u003e \"1; mode=block\",\n    \"x-content-type-options\" =\u003e \"nosniff\",\n    \"referrer-policy\" =\u003e \"strict-origin-when-cross-origin\"\n  }\n```\n\n## API Documentation\n\n### OpenAPI Specification\n\nAuto-generated API docs available at `/api/docs` (when enabled).\n\n### Key Endpoints\n\n```elixir\n# User Management\nPOST /api/users        # Create user\nPOST /api/sessions     # Login\nDELETE /api/sessions   # Logout\n\n# Learning Sessions\nGET /api/sessions      # List sessions\nPOST /api/sessions     # Create session\nWS /live/sessions/:id  # Real-time session\n\n# AI Features\nPOST /api/ai/analyze   # Analyze learning progress\nPOST /api/ai/tutor     # Request AI tutoring\nGET /api/ai/agents     # List available agents\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Documentation**: [docs/](docs/)\n- **API Reference**: `/api/docs`\n- **Task Management**: Use Task Master AI commands\n- **AI Agents**: Configure via BMAD system\n- **Community**: Join our Discord or Matrix channels\n\n## Roadmap\n\n### Phase 1: Core Platform (Complete)\n- [x] User authentication and profiles\n- [x] Basic learning sessions\n- [x] AI agent integration\n- [x] Task Master AI setup\n\n### Phase 2: Advanced Features (In Progress)\n- [ ] Viral sharing mechanics\n- [ ] Advanced analytics dashboard\n- [ ] Multi-language support\n- [ ] Mobile-responsive UI\n\n### Phase 3: Enterprise Features\n- [ ] Team and classroom management\n- [ ] Advanced reporting and compliance\n- [ ] Integration with LMS systems\n- [ ] White-label deployment options\n\n---\n\n*Vel Tutor - Empowering learning through intelligent, collaborative AI tutoring*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyrex41%2Fvel_tutor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpyrex41%2Fvel_tutor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyrex41%2Fvel_tutor/lists"}