{"id":50535255,"url":"https://github.com/dariomatias-dev/academic_planner_app","last_synced_at":"2026-06-03T16:01:08.705Z","repository":{"id":361628668,"uuid":"1189018322","full_name":"dariomatias-dev/academic_planner_app","owner":"dariomatias-dev","description":"Flutter reference project using MVVM + Clean Architecture + Feature-First, focused on scalable structure, modular design, and maintainable code organization for medium to large Flutter applications.","archived":false,"fork":false,"pushed_at":"2026-05-31T14:11:26.000Z","size":1430,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T16:11:07.832Z","etag":null,"topics":["clean-architecture","dart","feature-first","flutter","mobile","mvvm","mvvm-architecture","riverpod"],"latest_commit_sha":null,"homepage":"","language":"Dart","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/dariomatias-dev.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":null,"dco":null,"cla":null}},"created_at":"2026-03-22T22:07:51.000Z","updated_at":"2026-05-31T14:11:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dariomatias-dev/academic_planner_app","commit_stats":null,"previous_names":["dariomatias-dev/academic_planner_app"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dariomatias-dev/academic_planner_app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dariomatias-dev%2Facademic_planner_app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dariomatias-dev%2Facademic_planner_app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dariomatias-dev%2Facademic_planner_app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dariomatias-dev%2Facademic_planner_app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dariomatias-dev","download_url":"https://codeload.github.com/dariomatias-dev/academic_planner_app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dariomatias-dev%2Facademic_planner_app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33872298,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"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":["clean-architecture","dart","feature-first","flutter","mobile","mvvm","mvvm-architecture","riverpod"],"created_at":"2026-06-03T16:01:07.784Z","updated_at":"2026-06-03T16:01:08.698Z","avatar_url":"https://github.com/dariomatias-dev.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://img.shields.io/badge/Flutter-3.35.0-02569B?style=for-the-badge\u0026logo=flutter\u0026logoColor=white\" alt=\"Flutter\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/Dart-SDK%20^3.10.4-0175C2?style=for-the-badge\u0026logo=dart\u0026logoColor=white\" alt=\"Dart\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/Riverpod-3.3.1-08479E?style=for-the-badge\" alt=\"Riverpod\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/Architecture-MVVM%20%2B%20Clean%20%2B%20Feature--First-green?style=for-the-badge\" alt=\"Architecture\"\u003e\n\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cstrong\u003eLanguage:\u003c/strong\u003e\n\u003cstrong\u003eEnglish\u003c/strong\u003e | \u003ca href=\"README.pt.md\"\u003ePortuguês\u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eAcademic Planner\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  Reference project for \u003cstrong\u003eMVVM + Clean Architecture + Feature-First\u003c/strong\u003e architecture in Flutter.\n  \u003cbr\u003e\u003cbr\u003e\n  \u003ca href=\"https://github.com/dariomatias-dev/academic-planner/issues\"\u003eReport Bug\u003c/a\u003e ·\n  \u003ca href=\"https://github.com/dariomatias-dev/academic-planner/issues\"\u003eRequest Feature\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Table of Contents\n\n- [About the Project](#about-the-project)\n- [Features](#features)\n- [Architecture](#architecture)\n- [Folder Structure](#folder-structure)\n- [Key Technologies](#key-technologies)\n- [Getting Started](#getting-started)\n- [Documentation](#documentation)\n- [Author](#author)\n\n---\n\n## About the Project\n\nAcademic Planner is a student routine management application that serves as an **architectural reference project**. The main goal is not just the functionality itself, but to demonstrate how to structure a medium/large Flutter application using:\n\n- **Feature-First**: code organization by business domain\n- **Clean Architecture**: separation of concerns into layers with explicit dependency rules\n- **MVVM**: decoupling between UI and presentation logic\n\nEvery architectural decision is documented with its rationale. The project is intentional: there are no shortcuts that compromise the structure to gain development speed.\n\n---\n\n## Features\n\n| Feature             | Description                                                                               |\n| ------------------- | ----------------------------------------------------------------------------------------- |\n| Activities          | Create, edit, and delete academic activities with filters by status, date, and discipline |\n| Disciplines         | Manage disciplines by academic period with schedule and teacher details                   |\n| Agenda              | Calendar view with activities grouped by date                                             |\n| Notes               | Rich text editor for creating notes linked to disciplines                                 |\n| Schedule            | Weekly class schedule grid view                                                           |\n| Categories and Tags | Organize activities with custom categories and tags                                       |\n| Authentication      | Sign in, sign up, and password recovery via Firebase Auth                                 |\n| Settings            | Light/dark theme toggle with local persistence                                            |\n| About               | App info with version and source code link                                                |\n\n---\n\n## Architecture\n\nThe project combines three complementary approaches:\n\n```\nFeature-First  -\u003e  how code is organized into folders\nClean Arch     -\u003e  how layers communicate (dependency rules)\nMVVM           -\u003e  how the UI connects to business logic\n```\n\n### Why these three?\n\n**Feature-First** solves the organization problem: instead of grouping files by technical type (all models together, all screens together), it groups by business domain. Each feature is an isolated module - changing `activities` does not require opening other feature folders.\n\n**Clean Architecture** solves the dependency problem: it defines explicit rules about which layer can depend on which. The Domain (business rules) is pure Dart, with no external dependencies. The UI never accesses the database directly.\n\n**MVVM** solves the UI coupling problem: the screen never contains logic. The ViewModel manages screen state without depending on `BuildContext` - it is testable in isolation.\n\nInside each feature:\n\n```text\nfeatures/activities/\n├── domain/          # Entities and contracts (pure Dart, zero dependencies)\n├── data/            # Models, datasources, and repository implementations\n├── presentation/    # Screens, ViewModels, Providers, and Widgets\n└── di/              # Feature-specific dependency injection\n```\n\nData flow:\n\n```\nScreen -\u003e Provider -\u003e ViewModel -\u003e Repository (contract) -\u003e RepositoryImpl -\u003e DataSource\n```\n\n\u003e Full documentation with code examples: [docs/en/architecture.md](docs/en/architecture.md)\n\n---\n\n## Folder Structure\n\n```text\nlib/src/\n├── core/        # Global infrastructure (database, routes, theme, DI, logging, seeds)\n├── features/    # 17 isolated business modules\n└── shared/      # Design System and global utilities\n```\n\nExisting features: `about`, `activities`, `auth`, `calendar`, `categories`, `course_details`, `disciplines`, `home`, `notes`, `not_found`, `pdf_viewer`, `schedule`, `settings`, `splash`, `tags`, `teacher`, `users`.\n\n\u003e Full annotated folder tree: [docs/en/structure.md](docs/en/structure.md)\n\n---\n\n## Key Technologies\n\n| Technology       | Version | Role                       |\n| ---------------- | ------- | -------------------------- |\n| Flutter          | 3.35.0  | UI Framework               |\n| Dart SDK         | ^3.10.4 | Language                   |\n| flutter_riverpod | 3.3.1   | State management and DI    |\n| go_router        | 17.1.0  | Declarative navigation     |\n| sqflite          | 2.4.2   | Local persistence (SQLite) |\n| firebase_auth    | 6.4.0   | Authentication             |\n| cloud_firestore  | 6.3.0   | Cloud backend              |\n| flutter_quill    | 11.5.0  | Rich text editor           |\n\n\u003e Full list with exact versions and rationale for each choice: [docs/en/technologies.md](docs/en/technologies.md)\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n- Flutter 3.35.0+\n- Dart SDK ^3.10.4\n- Firebase project configured (for authentication and Firestore)\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/dariomatias-dev/academic-planner.git\n\n# Install dependencies\nflutter pub get\n\n# Run the application\nflutter run\n```\n\n### Development Seeds\n\nSeeds populate the database with sample data for development. Inactive by default, never run in release builds.\n\n```bash\n# Run app with seeds on first launch (debug only)\nflutter run --dart-define=SEED_ENABLED=true\n\n# Run seeds as a standalone script (no emulator needed)\ndart run scripts/seed.dart\n```\n\n---\n\n## Documentation\n\nDocumentation is organized into separate files by topic for easier navigation:\n\n| Document                                  | What you will find                                                                                                                            |\n| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| [Architecture](docs/en/architecture.md)   | Detailed explanation of MVVM, Clean Architecture, and Feature-First, with code examples from the project itself and rationale for each choice |\n| [Project Structure](docs/en/structure.md) | Full annotated folder tree, details of each section, and a table with all existing features                                                   |\n| [Navigation](docs/en/navigation.md)       | How the routing system works with GoRouter, complete route reference, and a guide for adding new routes                                       |\n| [Technologies](docs/en/technologies.md)   | All dependencies with exact versions (from `pubspec.lock`) and reason for each choice                                                         |\n\n---\n\n## Author\n\nDeveloped by **Dário Matias**:\n\n- Portfolio: [https://dariomatias-dev.com](https://dariomatias-dev.com)\n- GitHub: [https://github.com/dariomatias-dev](https://github.com/dariomatias-dev)\n- Email: [matiasdario75@gmail.com](mailto:matiasdario75@gmail.com)\n- Instagram: [https://instagram.com/dariomatias_dev](https://instagram.com/dariomatias_dev)\n- LinkedIn: [https://linkedin.com/in/dariomatias-dev](https://linkedin.com/in/dariomatias-dev)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdariomatias-dev%2Facademic_planner_app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdariomatias-dev%2Facademic_planner_app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdariomatias-dev%2Facademic_planner_app/lists"}