{"id":51987803,"url":"https://github.com/gradely/project-docs","last_synced_at":"2026-07-30T21:01:22.167Z","repository":{"id":367004493,"uuid":"1050154407","full_name":"gradely/project-docs","owner":"gradely","description":"A single place for guides, references, and documentation across all projects.","archived":false,"fork":false,"pushed_at":"2025-09-29T05:35:35.000Z","size":28,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T08:06:33.673Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gradely.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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-09-04T03:05:11.000Z","updated_at":"2025-10-16T02:04:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gradely/project-docs","commit_stats":null,"previous_names":["gradely/project-docs"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/gradely/project-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gradely%2Fproject-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gradely%2Fproject-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gradely%2Fproject-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gradely%2Fproject-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gradely","download_url":"https://codeload.github.com/gradely/project-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gradely%2Fproject-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36091646,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-30T02:00:05.956Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-07-30T21:01:21.438Z","updated_at":"2026-07-30T21:01:22.147Z","avatar_url":"https://github.com/gradely.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gradely Backend Services\n\nWelcome to the Gradely backend services documentation! This repository serves as the central hub for understanding and integrating with the Gradely educational platform's backend architecture.\n\n## 🏗️ Architecture Overview\n\nGradely's backend is built as a microservices architecture consisting of three core services that work together to provide a comprehensive educational platform:\n\n```mermaid\ngraph TB\n    subgraph \"Backend Services\"\n        API[Gradely API v2\u003cbr/\u003ePHP/Yii2]\n        MAIN[Gradely-2.1\u003cbr/\u003eGo/Gin]\n        NOTIF[Notification Service\u003cbr/\u003eGo/Gin]\n    end\n\n    subgraph \"External Services\"\n        FIREBASE[Firebase\u003cbr/\u003ePush Notifications]\n        AWS_EMAIL[AWS\u003cbr/\u003eEmail]\n        PAYSTACK[Paystack\u003cbr/\u003ePayments]\n        AWS_S3[AWS\u003cbr/\u003eS3 File Storage]\n    end\n\n    subgraph \"Infrastructure\"\n        MYSQL[(MySQL\u003cbr/\u003eDatabase)]\n        NOTIF_MYSQL[(Notification MySQL\u003cbr/\u003eDatabase)]\n        REDIS[(Redis\u003cbr/\u003eCache)]\n    end\n\n    API --\u003e MYSQL\n    MAIN --\u003e MYSQL\n    NOTIF --\u003e NOTIF_MYSQL\n    MAIN --\u003e REDIS\n    MAIN --\u003e AWS_S3\n    API --\u003e AWS_S3\n    NOTIF --\u003e AWS_S3\n    NOTIF --\u003e AWS_EMAIL\n    NOTIF --\u003e FIREBASE\n    MAIN --\u003e PAYSTACK\n```\n\n## 🚀 Core Services\n\n### 1. [Gradely API v2](https://github.com/gradely/gradely-api) - Legacy API Service\n\n**Technology**: PHP 7.4+ with Yii2 Framework  \n**Port**: Configurable via environment variable  \n**Purpose**: Legacy API endpoints and user authentication\n\n**Key Features**:\n\n- User authentication and authorization\n- Legacy API endpoints for backward compatibility\n- Basic educational content management\n- User onboarding and profile management\n\n**Documentation**: [📁 Repository](https://github.com/gradely/gradely-api) | [🔧 Swagger UI](http://localhost:\u003cyour-port\u003e/docs)\n\n\u003e **Note:** Replace `\u003cyour-port\u003e` with the port configured in your environment variables for each service. The default ports are typically 8080 or 8081, but may vary depending on your setup.\n\n---\n\n### 2. [Gradely-2.1](https://github.com/gradely/gradely-2.1) - Main API Service\n\n**Technology**: Go with Gin Framework  \n**Port**: Configurable via environment variable  \n**Purpose**: Core educational platform functionality\n\n**Key Features**:\n\n- **Authentication \u0026 Authorization**: JWT-based user management\n- **Student Management**: Learning progress, homework, assessments\n- **Teacher Tools**: Class management, grading, live sessions\n- **Parent Dashboard**: Student monitoring and progress tracking\n- **School Administration**: Multi-school management\n- **Payment Processing**: Subscription and payment handling\n- **Live Classes**: Real-time tutoring and live sessions\n- **AI Integration**: Adaptive learning recommendations\n- **Content Management**: Educational resources and libraries\n\n**Documentation**: [📁 Repository](https://github.com/gradely/gradely-2.1) | [🔧 Swagger UI](http://localhost:\u003cyour-port\u003e/docs)\n\n\u003e **Note:** Replace `\u003cyour-port\u003e` with the port configured in your environment variables for each service. The default ports are typically 8080 or 8081, but may vary depending on your setup.\n\n---\n\n### 3. [Notification Service v2.1](https://github.com/gradely/notification-v2.1) - Communication Service\n\n**Technology**: Go with Gin Framework  \n**Port**: Configurable via environment variable  \n**Purpose**: Multi-channel notification delivery\n\n**Key Features**:\n\n- **Multi-Channel Support**: Email, SMS, WhatsApp, Push notifications\n- **User-Specific Notifications**: Parents, Teachers, Students, Schools\n- **Template System**: HTML and text email templates\n- **Blacklist Management**: User preference handling\n- **Firebase Integration**: Push notifications\n- **Third-Party Integrations**: Twilio, Termii\n- **Background Processing**: Asynchronous notification delivery\n\n**Documentation**: [📁 Repository](https://github.com/gradely/notification-v2.1) | [🔧 Swagger UI](http://localhost:\u003cyour-port\u003e/docs)\n\n\u003e **Note:** Replace `\u003cyour-port\u003e` with the port configured in your environment variables for each service. The default ports are typically 8080 or 8081, but may vary depending on your setup.\n\n## 🔄 Service Communication\n\n### API Flow\n\n1. **All services** → **MySQL** (shared database)\n2. **Gradely-2.1** → **Redis** (caching/session management)\n3. **Gradely-2.1** → **Notification Service** (User notifications)\n4. **Gradely-2.1** → **External Services** (Payments, Storage, etc.)\n\n### Integration Patterns\n\n#### Gradely-2.1 → Notification Service\n\n```go\n// Example: Sending a notification from Gradely-2.1\nnotification := \u0026NotificationModel{\n    ActionName: \"new_homework_parent\",\n    ReceiverID: \"12345\",\n    ActionData: map[string]interface{}{\n        \"student_name\": \"John Doe\",\n        \"subject\": \"Mathematics\",\n        \"homework_title\": \"Algebra Practice\",\n        \"due_date\": \"2024-01-15\",\n        \"teacher_name\": \"Mrs. Smith\",\n    },\n}\n\nerr := notification.SendNotification(config)\n```\n\n#### HTTP Endpoints\n\n- **Notification Service**: `POST /notification/v2.1/`\n- **Blacklist Check**: `POST /notification/v2.1/check-blacklist-contact`\n- **Test Notifications**: `POST /notification/v2.1/test`\n\n## 🛠️ Development Setup\n\n### Prerequisites\n\n- **Docker** and `docker compose`\n- **Go** 1.17+ (for Gradely-2.1 and Notification Service)\n- **PHP** 7.4+ and **Composer** (for Gradely API v2)\n- **MySQL** 5.7+\n- **Redis**\n\n### Quick Start\n\n1. **Clone all repositories**:\n\n   ```bash\n   git clone https://github.com/gradely/gradely-api.git\n   git clone https://github.com/gradely/gradely-2.1.git\n   git clone https://github.com/gradely/notification-v2.1.git\n   ```\n\n2. **Start Gradely-2.1** (Main Service):\n\n   ```bash\n   cd gradely-2.1\n   cp .env_services_sample .env\n   # Edit .env with your settings\n   make dev  # Starts all services with Docker\n   ```\n\n3. **Start Notification Service**:\n\n   ```bash\n   cd notification-v2.1\n   cp .env-sample .env\n   # Edit .env with your settings\n   go run main.go\n   ```\n\n4. **Start Gradely API v2** (Legacy):\n   ```bash\n   cd gradely-api\n   composer install\n   cp config/var.php.example config/var.php\n   # Edit config/var.php with your settings\n   php yii serve\n   ```\n\n### Service URLs (Development)\n\n- **Gradely API v2**: http://localhost:8080/docs\n- **Gradely-2.1**: http://localhost:8081/docs\n- **Notification Service**: http://localhost:8080/docs (or configured port)\n\n## 📊 API Documentation\n\nEach service provides comprehensive Swagger/OpenAPI documentation:\n\n| Service                  | Local Docs                                                             | Production Docs                                                              | Repository                                                    |\n| ------------------------ | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------- |\n| **Gradely API v2**       | [http://localhost:\u003cyour-port\u003e/docs](http://localhost:\u003cyour-port\u003e/docs) | [https://api.gradely.ng/docs](https://api.gradely.ng/docs)                   | [📁 Repository](https://github.com/gradely/gradely-api)       |\n| **Gradely-2.1**          | [http://localhost:\u003cyour-port\u003e/docs](http://localhost:\u003cyour-port\u003e/docs) | [https://api.gradely.ng/docs](https://api.gradely.ng/docs)                   | [📁 Repository](https://github.com/gradely/gradely-2.1)       |\n| **Notification Service** | [http://localhost:\u003cyour-port\u003e/docs](http://localhost:\u003cyour-port\u003e/docs) | [https://notification.gradely.co/docs](https://notification.gradely.co/docs) | [📁 Repository](https://github.com/gradely/notification-v2.1) |\n\n\u003e **Note:** Replace `\u003cyour-port\u003e` with the port configured in your `.env` file for each service.\n\n## 🔐 Authentication\n\nAll services use JWT-based authentication:\n\n```bash\n# Include in request headers\nAuthorization: Bearer \u003cyour_jwt_token\u003e\n```\n\n### User Types\n\n- **Student**: Regular student users\n- **Teacher**: Teachers and tutors\n- **Parent**: Parent/guardian accounts\n- **School**: School administrator accounts\n\n## 📱 Notification System\n\nThe notification service supports multiple channels and user types:\n\n### Supported Channels\n\n- **Email**: HTML and text templates\n- **SMS**: Via Twilio and Termii\n- **WhatsApp**: Via Twilio\n- **Push Notifications**: Via Firebase\n\n### Common Notification Types\n\n- **Parent**: Homework assignments, exam schedules, progress reports\n- **Teacher**: Student submissions, class reminders, performance updates\n- **Student**: Assignment reminders, achievement notifications\n- **School**: System updates, usage reports, administrative alerts\n\n## 🗄️ Database Architecture\n\n### Shared Databases\n\n- **MySQL**: Primary data storage\n- **Redis**: Caching and session management (only Gradely-2.1 connects)\n\n### Database Separation\n\n- **Gradely-2.1**: Main application database\n- **Notification Service**: Notification-specific tables\n- **Gradely API v2**: Legacy data and user authentication\n\n## 🚀 Deployment\n\n### Production URLs\n\n- **Gradely API v2**: https://api.gradely.ng\n- **Gradely-2.1**: https://api.gradely.ng/v2.1\n- **Notification Service**: https://notification.gradely.co\n\n### Environment Configuration\n\nEach service has its own configuration:\n\n- **Gradely-2.1**: `.env`\n- **Notification Service**: `.env`\n- **Gradely API v2**: `config/var.php`\n\n## 🤝 Contributing\n\n### Development Workflow\n\n1. Fork the relevant repository\n2. Create a feature branch\n3. Make your changes\n4. Test with all three services\n5. Submit a pull request\n\n### Code Standards\n\n- **Go**: Follow Go conventions and best practices\n- **PHP**: Follow PSR-12 coding standards\n- **Documentation**: Update Swagger docs for API changes\n- **Testing**: Write tests for new features\n\n## 📞 Support\n\n### Getting Help\n\n- **Documentation**: Check individual service READMEs\n- **Issues**: Create GitHub issues in relevant repositories\n- **Email**: dev@gradely.ng\n- **Swagger UI**: Interactive API testing and documentation\n\n### Common Issues\n\n- **Port Conflicts**: Ensure services run on different ports\n- **Database Connections**: Verify MySQL and Redis are running\n- **Authentication**: Check JWT token validity\n- **Notifications**: Verify Firebase and Twilio configurations\n\n## 📄 License\n\nThis project is proprietary software owned by Gradely.\n\n---\n\n**Made with ❤️ by the Gradely Team**\n\n_For detailed documentation of each service, please visit their individual repositories and Swagger documentation._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgradely%2Fproject-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgradely%2Fproject-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgradely%2Fproject-docs/lists"}