Maestro

App mobile para gestão pedagógica musical do GEM de Vargem Grande do Sul

Mobile app for musical pedagogical management at GEM Vargem Grande do Sul

PT-BR • English • Live Demo · Stack • Quick Start • Build Android • Autor

Live Demo · 📦 Repositório • 🌐 Portfólio • 💼 LinkedIn

🇧🇷 PT-BR

🎼 Visão geral

Maestro é um aplicativo mobile criado para digitalizar e organizar a operação pedagógica musical do GEM de Vargem Grande do Sul.

O app substitui cadernos, fichas soltas e planilhas fragmentadas por um fluxo centralizado para cadastro de alunos, professores, métodos, aulas, presença, evolução musical, analytics e relatórios internos.

A proposta é tratar o acompanhamento musical como um sistema pedagógico contínuo, e não como uma coleção de anotações isoladas.

Objetivo: registrar aulas, acompanhar evolução musical e gerar relatórios pedagógicos em um fluxo compartilhado, confiável e prático para uso real da equipe.

🎯 Problema que resolve

Antes do Maestro, o acompanhamento pedagógico dependia de registros manuais, memória da equipe e consolidação manual de informações.

Isso dificultava:

saber o que cada aluno estudou de fato;
acompanhar evolução ao longo do tempo;
identificar estagnação, aceleração ou queda de desempenho;
consolidar relatórios por instrumento, grupo ou período;
compartilhar a operação entre instrutores e encarregados;
manter um histórico pedagógico consistente.

O Maestro resolve esse problema criando uma camada digital para registrar, consultar, analisar e exportar informações pedagógicas com mais clareza.

👥 Para quem foi feito

O app foi pensado para uso real por:

Instrutores que lançam aulas no dia a dia.
Encarregados locais e regionais que acompanham alunos e equipes.
Coordenação pedagógica que precisa de relatórios e visão consolidada.
Equipe do GEM que precisa operar em conjunto dentro da mesma organização.

✨ Funcionalidades principais

👥 Alunos

Cadastro completo de alunos.
Edição, filtros e exclusão.
Campos pedagógicos e administrativos no mesmo fluxo.
Organização por instrumento, família, nível, graduação, congregação e status.
Histórico individual conectado aos registros de aula.

🎼 Aulas

Registro detalhado de aulas individuais e teóricas.
Seleção de professor e método.
Conteúdo musical estruturado.
Páginas, itens de lição, hinos, vozes e solfejo.
Observações pedagógicas.
Presença vinculada ao lançamento.
Habilidades avaliadas de forma estruturada.

📈 Analytics

KPIs individuais por aluno.
Evolução mensal.
Score médio.
Delta de progresso.
Radar de habilidades.
Alertas de estagnação, aceleração e declínio.
Visão coletiva do grupo por período.

📊 Relatórios

Ranking de alunos.
Média por instrumento.
Distribuição por nível.
Crescimento do grupo.
Alertas de alunos sem registro recente.
Exportação em PDF, Excel, PNG e JSON.

🧑‍🏫 Professores e equipe

Cadastro de professores e encarregados.
Papéis como Instrutor, Encarregado Local e Encarregado Regional.
Uso compartilhado por organização no Supabase.
Entrada automática em equipe por código.

🧰 Métodos

Cadastro e gerenciamento de métodos.
Vínculo com instrumentos.
Catálogo musical embutido em JSON.
Suporte a métodos oficiais usados no contexto do GEM.

⚙️ Operação

Autenticação com e-mail e senha.
Modo convidado.
Tema claro/escuro com persistência.
Logs locais exportáveis.
ErrorBoundary global.
Contexto operacional compartilhado entre telas.

🧩 Telas e módulos

Tela Principal / Shell
Alunos
Detalhe do aluno
Aulas
Central de Aulas
Presença
Metas
Grupos
Grupos de Teoria
Tela de Hoje
Professores
Métodos
Dashboard
Relatórios
Configurações
Logs
Login

🇺🇸 English

🎼 Overview

Maestro is a mobile application created to digitize and organize the musical pedagogical operation of GEM Vargem Grande do Sul.

The app replaces notebooks, loose records and fragmented spreadsheets with a centralized workflow for students, teachers, methods, lessons, attendance, musical progress, analytics and internal reports.

The goal is to treat musical education tracking as a continuous pedagogical system, not as a collection of isolated notes.

Goal: register lessons, track musical progress and generate pedagogical reports through a shared, reliable and practical workflow for real team usage.

🎯 Problem solved

Before Maestro, pedagogical tracking depended on manual records, team memory and manual consolidation of information.

This made it difficult to:

know what each student actually studied;
compare progress over time;
identify stagnation, acceleration or performance decline;
consolidate reports by instrument, group or period;
share the operation between instructors and coordinators;
maintain a consistent pedagogical history.

Maestro solves this by creating a digital layer to register, query, analyze and export pedagogical information with greater clarity.

👥 Who it was built for

The app was designed for real use by:

Instructors who register lessons in daily routines.
Local and regional coordinators who track students and teams.
Pedagogical coordination that needs reports and consolidated views.
GEM teams that need to work together inside the same organization.

✨ Key features

👥 Students

Complete student registration.
Editing, filtering and deletion.
Pedagogical and administrative fields in the same workflow.
Organization by instrument, family, level, graduation, congregation and status.
Individual history connected to lesson records.

🎼 Lessons

Detailed registration of individual and theoretical lessons.
Teacher and method selection.
Structured musical content.
Pages, lesson items, hymns, voices and solfege.
Pedagogical notes.
Attendance linked to lesson records.
Structured skill assessment.

📈 Analytics

Individual student KPIs.
Monthly evolution.
Average score.
Progress delta.
Skill radar.
Alerts for stagnation, acceleration and decline.
Collective group view by period.

📊 Reports

Student ranking.
Average by instrument.
Level distribution.
Group growth.
Alerts for students with no recent records.
Export to PDF, Excel, PNG and JSON.

🧑‍🏫 Teachers and team

Teacher and coordinator registration.
Roles such as Instructor, Local Coordinator and Regional Coordinator.
Shared usage through Supabase organization.
Automatic team entry by code.

🧰 Methods

Method registration and management.
Instrument association.
Embedded musical catalog in JSON.
Support for official methods used in the GEM context.

⚙️ Operation

Email/password authentication.
Guest mode.
Persistent light/dark theme.
Exportable local logs.
Global ErrorBoundary.
Shared operational context across screens.

Live Demo

Surface	URL
Public demo	https://maestro-demo-tau.vercel.app
GitHub	https://github.com/BarujaFe1/Maestro

Web demo for portfolio browsing. Core product remains the Expo/React Native app with Supabase.

🛠️ Stack / Tecnologias

Tecnologia	Versão	Uso no projeto
React Native	0.81.5	Base do app mobile
React	19.1.0	Camada de interface e estado
Expo	54	Tooling, runtime e integração nativa
React Navigation	Expo 54 compatible	Drawer + Native Stack navigation
Supabase JS	2.98	Auth, database and RPC
AsyncStorage	—	Local persistence for theme and auxiliary states
Day.js	—	Date handling and formatting
React Native Chart Kit	—	Evolution charts and analytics
React Native SVG	—	Graphic base for charts
Expo Print	—	PDF generation
Expo Sharing	—	File sharing
Expo File System	—	Reading/writing exported files
React Native View Shot	—	Chart capture as image
XLSX	—	`.xlsx` export
Gradle / Android Native	Local SDK	Local release APK generation
EAS Build	Configured profiles	Remote APK and App Bundle builds

🏗️ Arquitetura / Architecture

Visão geral / Overview

O projeto separa claramente:

interface reutilizável;
contexto global;
catálogos e dados estáticos;
serviços de acesso a dados;
regras utilitárias;
telas de fluxo;
integrações nativas e build.

The project clearly separates:

reusable interface;
global context;
catalogs and static data;
data access services;
utility rules;
user flow screens;
native integrations and build.

Estrutura em alto nível / High-level structure

src/
├── components/
├── constants/
├── context/
├── data/
├── lib/
├── navigation/
├── screens/
├── services/
├── theme/
└── utils/

supabase/
└── migrations/

docs/
└── setup and complementary documentation

Árvore comentada / Commented tree

src/
├── components/              # Reusable UI components and visual blocks
│   ├── AppUI
│   ├── BottomNavBar
│   ├── BulkEntryField
│   ├── CollapsibleSection
│   ├── DrawerMenuButton
│   ├── ErrorBoundary
│   ├── KpiCard
│   ├── LessonTypeTabs
│   ├── MultiSelectModal
│   ├── RadarChart
│   ├── ScoreInputRow
│   ├── SelectModal
│   └── UnitSwitcher
│
├── constants/               # Domain enums and constants
│   ├── lessonTypes.js
│   └── units.js
│
├── context/                 # Global application context
│   ├── AuthContext.js
│   └── OperationalContext.js
│
├── data/                    # Local catalogs and embedded methods
│   ├── catalogs.js
│   └── methodCatalog/
│
├── lib/                     # Central external clients
│   └── supabase.js
│
├── navigation/              # Navigation configuration
│   └── AppNavigator.js
│
├── screens/                 # Application screens
│   ├── AttendanceScreen.js
│   ├── DashboardScreen.js
│   ├── LessonCenterScreen.js
│   ├── LoginScreen.js
│   ├── LogsScreen.js
│   ├── MainShellScreen.js
│   ├── MethodsScreen.js
│   ├── ReportsScreen.js
│   ├── SettingsScreen.js
│   ├── StudentDetailScreen.js
│   ├── StudentsScreen.js
│   ├── TeachersScreen.js
│   ├── TodayScreen.js
│   ├── TheoryGroupsScreen.js
│   └── auxiliary screens
│
├── services/                # Data access and CRUD/query rules
│   ├── db.js
│   └── org.js
│
├── theme/                   # Light/dark theme and visual tokens
│   └── ThemeProvider.js
│
└── utils/                   # Analytics, parsing, export and normalization
    ├── analytics.js
    ├── attendanceStore.js
    ├── bulkInputParser.js
    ├── calendarRules.js
    ├── errorHandler.js
    ├── exporters.js
    ├── lessonAdapters.js
    ├── lessonPayload.js
    ├── logger.js
    ├── methodCatalog.js
    ├── normalizers.js
    ├── pedagogy.js
    ├── reportInsights.js
    ├── reporting.js
    └── theoryGroupsStore.js

🗄️ Banco de dados / Database

Entidades principais / Main entities

organizations
    └──< profiles
            └──< students
            └──< teachers
            └──< methods
            └──< lessonrecords

students
    └──< lessonrecords >── teachers
                     └──> methods

Relacionamentos principais / Main relationships

Uma organization agrupa perfis, alunos, professores e registros.
Um profile representa o usuário autenticado.
Um student pode ter vários registros em lessonrecords.
Um teacher pode lançar várias aulas.
Um method pode ser associado a vários registros de aula.
joinOrgByCode conecta o usuário a uma organização compartilhada.

Tabelas principais / Main tables

`profiles`

id
fullname
role
orgid

Used to identify the authenticated user, define the role and anchor the shared organization scope.

`organizations`

id
name
joincode

Represents the shared team/organization and controls access by code.

`students`

id
fullname
instrument
family
level
graduation
congregation
status
startdate
observations
address
phone
birthdate
baptismdate
instrumentchangenote
ownerid

Stores the pedagogical and administrative student profile.

`teachers`

id
fullname
instrument
congregation
rolekind
active

Stores instructors and coordinators.

`methods`

id
name
instruments
active
notes

Manages methods and integrates with the embedded catalog.

`lessonrecords`

id
studentid
teacherid
methodid
lessondate
contentgroup
contentnumber
voices
solfejo
observations
contentitems[]
pageitems[]
lessonitems[]
skillrhythm
skillreading
skilltechnique
skillposture
skillmusicality
attendance
launchedat

Core table for pedagogical tracking.

🔐 RPCs

`joinOrgByCode`

Connects an authenticated user to a shared organization/team through an organization code.

🚀 Quick Start / Início rápido

Pré-requisitos / Requirements

Node.js 20+ recommended
npm or pnpm
Expo CLI through npx
Android Studio with Android SDK
Java 17
ADB configured in PATH
Configured Supabase project
Android device with Expo Go or Android emulator

Clonar o repositório / Clone repository

git clone https://github.com/BarujaFe1/Maestro.git
cd Maestro

Instalar dependências / Install dependencies

npm install

Configurar variáveis de ambiente / Configure environment

Create a .env file in the project root:

EXPO_PUBLIC_SUPABASE_URL=https://SEU-PROJETO.supabase.co
EXPO_PUBLIC_SUPABASE_ANON_KEY=sua_chave_anon
EXPO_PUBLIC_ORG_JOIN_CODE=CODIGO_DA_EQUIPE

Rodar com Expo / Run with Expo

npx expo start

Tunnel mode, useful when the device is not on the same network:

npx expo start --tunnel

Android físico com Expo Go / Physical Android with Expo Go

Install Expo Go on the phone.
Run:

npx expo start --tunnel

Scan the QR Code with Expo Go.

Emulador Android / Android emulator

With the emulator already open:

npx expo start

Then press a in the Expo terminal.

📱 Build Android

Requisitos / Requirements

Java 17
Android Studio
Android SDK
Android environment variables configured
android/ folder present in the project
Functional Gradle setup

Windows environment example

$env:JAVA_HOME="C:\Program Files\Java\jdk-17"
$env:ANDROID_HOME="$env:LOCALAPPDATA\Android\Sdk"
$env:Path += ";$env:ANDROID_HOME\platform-tools"
$env:Path += ";$env:ANDROID_HOME\emulator"
$env:Path += ";$env:ANDROID_HOME\cmdline-tools\latest\bin"

Local release APK via Gradle

cd android
.\gradlew.bat assembleRelease

Generated APK:

android/app/build/outputs/apk/release/app-release.apk

Install through ADB:

adb install -r android/app/build/outputs/apk/release/app-release.apk

EAS profiles

The project also supports EAS profiles:

development
preview — internal APK
production — App Bundle

Example:

eas build --platform android --profile preview

⚙️ Supabase Setup / Configuração do Supabase

Required setup:

Supabase project created.
Authentication enabled.
Main tables created.
Migrations applied.
RPC joinOrgByCode available.
Initial organization created.
Team code defined.

Migrations

Migrations are stored in:

supabase/

They can be applied through Supabase CLI or directly through the Supabase SQL editor.

Organization flow

Create the organization in organizations.
Define a joincode.
Configure EXPO_PUBLIC_ORG_JOIN_CODE when relevant.
Let users automatically join the team through joinOrgByCode.

🧠 Technical decisions / Decisões técnicas

Expo with native Android folder

The project uses Expo for fast iteration while keeping a native Android output for predictable local Gradle builds.

Supabase

Supabase was chosen because the project needs authentication, relational data, RPC, shared team usage and simple JavaScript/TypeScript integration.

In-app analytics

Analytics live inside the app because many pedagogical decisions need to be available during lessons, follow-ups and internal meetings.

Local exports

Local export reduces friction for internal use, allowing the team to generate PDFs, spreadsheets, images, backups and reports without an external dashboard.

Organization by code

A team code reduces onboarding friction and centralizes the shared pedagogical operation.

🗺️ Roadmap

Implementado / Implemented

Email/password authentication.
Guest mode.
Automatic organization entry by code.
Complete student registration.
Teacher/coordinator registration.
Method registration and management.
Detailed lesson records.
Individual analytics.
Collective analytics.
Export to PDF, Excel, PNG and JSON.
Exportable local logs.
Persistent light/dark theme.
JSON method catalog.
Drawer + Native Stack navigation.
Global ErrorBoundary.

Em desenvolvimento / In development

Continuous operational UX refinements.
Theory groups and group attendance flow.
Performance adjustments for large lists.
Evolution of goals and group pedagogical modeling.

Planejado / Planned

Additional pedagogical goals consolidation.
Better reports by group/team.
Internal distribution improvements.
Expansion of musical catalogs.
Broader pedagogical metrics coverage.

🤝 Contribuição / Contributing

Conventional commits

feat: adiciona exportação de relatório por instrumento
fix: corrige cálculo de delta de progresso
refactor: simplifica normalização de lessonrecords
docs: atualiza instruções de build Android

Recommended flow

git checkout -b feat/nome-da-feature

Open a Pull Request with:

problem context;
change scope;
screenshots or GIFs when UI is involved;
database or migration notes, if applicable.

Bug reports

When reporting an issue, include:

affected screen;
expected behavior;
current behavior;
steps to reproduce;
terminal log;
exported app log, if applicable;
Android version and device.

👤 Autor / Author

Developed by Felipe Alirio Baruja.

Portfolio: https://barujafe.vercel.app/
GitHub: github.com/BarujaFe1
LinkedIn: linkedin.com/in/barujafe
Repository: github.com/BarujaFe1/Maestro

📄 License / Licença

MIT License.

See LICENSE for details.

📝 Observações finais / Final notes

O Maestro não é um app genérico de escola. Ele foi modelado para o contexto específico do GEM de Vargem Grande do Sul, com foco em:

ensino musical coletivo;
acompanhamento pedagógico contínuo;
operação compartilhada entre equipe;
relatórios úteis para decisão real.

If adapting the project to another context, start by reviewing:

musical catalogs;
team roles;
database organization;
pedagogical rules and metrics.

Maestro

Gestão pedagógica musical com clareza, histórico e evolução.

Musical pedagogy management with clarity, history and progress tracking.

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
android		android
assets		assets
docs		docs
src		src
supabase		supabase
.gitignore		.gitignore
App.js		App.js
LICENSE		LICENSE
README.md		README.md
app.json		app.json
babel.config.js		babel.config.js
eas.json		eas.json
icon.png		icon.png
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

Maestro

🇧🇷 PT-BR

🎼 Visão geral

🎯 Problema que resolve

👥 Para quem foi feito

✨ Funcionalidades principais

👥 Alunos

🎼 Aulas

📈 Analytics

📊 Relatórios

🧑‍🏫 Professores e equipe

🧰 Métodos

⚙️ Operação

🧩 Telas e módulos

🇺🇸 English

🎼 Overview

🎯 Problem solved

👥 Who it was built for

✨ Key features

👥 Students

🎼 Lessons

📈 Analytics

📊 Reports

🧑‍🏫 Teachers and team

🧰 Methods

⚙️ Operation

Live Demo

🛠️ Stack / Tecnologias

🏗️ Arquitetura / Architecture

Visão geral / Overview

Estrutura em alto nível / High-level structure

Árvore comentada / Commented tree

🗄️ Banco de dados / Database

Entidades principais / Main entities

Relacionamentos principais / Main relationships

Tabelas principais / Main tables

profiles

organizations

students

teachers

methods

lessonrecords

🔐 RPCs

joinOrgByCode

🚀 Quick Start / Início rápido

Pré-requisitos / Requirements

Clonar o repositório / Clone repository

Instalar dependências / Install dependencies

Configurar variáveis de ambiente / Configure environment

Rodar com Expo / Run with Expo

Android físico com Expo Go / Physical Android with Expo Go

Emulador Android / Android emulator

📱 Build Android

Requisitos / Requirements

Windows environment example

Local release APK via Gradle

EAS profiles

⚙️ Supabase Setup / Configuração do Supabase

Migrations

Organization flow

🧠 Technical decisions / Decisões técnicas

Expo with native Android folder

Supabase

In-app analytics

Local exports

Organization by code

🗺️ Roadmap

Implementado / Implemented

Em desenvolvimento / In development

Planejado / Planned

🤝 Contribuição / Contributing

Conventional commits

Recommended flow

Bug reports

👤 Autor / Author

📄 License / Licença

`profiles`

`organizations`

`students`

`teachers`

`methods`

`lessonrecords`

`joinOrgByCode`

Packages