From 5c480b929fd2396800fef5500474716068833ab1 Mon Sep 17 00:00:00 2001 From: Alex Kanunnikov Date: Sun, 1 Mar 2026 21:44:51 +0000 Subject: [PATCH 1/4] Update frontend README to match actual project info Rewrite the README with accurate project description, tech stack table, architecture overview, data flow diagram, development commands, test accounts, key routes, and correct license (CC0 1.0). Add status badges. Co-Authored-By: Claude Opus 4.6 --- frontend/README.md | 160 ++++++++++++++++++++++++++++++++------------- 1 file changed, 115 insertions(+), 45 deletions(-) diff --git a/frontend/README.md b/frontend/README.md index 44451b26d..5c18c93d3 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1,67 +1,137 @@ -# brn user UI +# Brain Up - Frontend -This part of BRN project responsible for end-user UI. +[![GitHub Stars](https://img.shields.io/github/stars/Brain-up/brn?style=flat-square)](https://github.com/Brain-up/brn) +[![License: CC0-1.0](https://img.shields.io/badge/License-CC0_1.0-lightgrey.svg?style=flat-square)](https://creativecommons.org/publicdomain/zero/1.0/) +[![Website](https://img.shields.io/website?url=https%3A%2F%2Fbrainup.site&style=flat-square&label=brainup.site)](https://brainup.site) -## Tech Stack +**[Brain Up](https://brainup.site)** is a web application for auditory training, designed to help people with central auditory processing deficits improve their listening skills. It supports children (7+), adults, and elderly users, including cochlear implant and hearing aid wearers, through progressive series of audio exercises. -* **Framework:** Ember.js 4.12 (Octane) -* **Data Layer:** [WarpDrive](https://github.com/emberjs/data) 5.8.1 (successor to ember-data) -* **Language:** TypeScript 5.9 -* **Styling:** Tailwind CSS -* **Auth:** Firebase + ember-simple-auth -* **Testing:** QUnit + ember-cli-mirage +This directory contains the **frontend** application — an Ember.js Octane SPA that drives the user-facing experience. -### Data Architecture +--- -The app uses WarpDrive's schema-driven architecture: +## Tech Stack -* **Schemas** (`app/schemas/`) — JSON schema definitions for all model types, replacing class-based `@attr`/`@belongsTo`/`@hasMany` models -* **Handlers** (`app/handlers/`) — `AuthHandler` injects auth tokens; `BrnApiHandler` normalizes the backend's REST responses to JSON:API format for the WarpDrive cache -* **Transformations** (`app/transformations/`) — Custom field transformations (`full-date` for Luxon DateTime, `array` for array fields) -* **Store** (`app/services/store.ts`) — Configured with a `RequestManager` pipeline: Auth → API normalization → Fetch → Cache +| Layer | Technology | +|-------|------------| +| **Framework** | [Ember.js](https://emberjs.com/) 4.12 (Octane) | +| **Language** | TypeScript 5.9 (strict mode) | +| **Data** | [WarpDrive](https://github.com/emberjs/data) 5.8.1 — schema-driven, replaces ember-data | +| **Styling** | Tailwind CSS + PostCSS + PurgeCSS | +| **Auth** | Firebase + ember-simple-auth | +| **Audio** | Tone.js | +| **Charts** | Billboard.js | +| **i18n** | ember-intl (English, Russian) | +| **Testing** | QUnit + ember-cli-mirage + ember-cli-code-coverage | +| **CI** | GitHub Actions | + +## Architecture + +``` +app/ +├── authenticators/ # Firebase & OAuth2 auth strategies +├── components/ # 36+ Glimmer components (task-player, audio-player, skeleton, ui/...) +├── controllers/ # Route-specific state +├── handlers/ # WarpDrive request pipeline handlers +│ ├── auth-handler # → injects Firebase auth tokens +│ └── brn-api-handler # → normalizes REST → JSON:API +├── helpers/ # Template helpers +├── modifiers/ # Glimmer element modifiers +├── routes/ # Route definitions & model hooks +├── schemas/ # WarpDrive model schemas (16 types) +├── services/ # Singletons (store, audio, network, stats, timers, ...) +├── styles/ # Tailwind config & app CSS +├── templates/ # Handlebars templates (incl. skeleton loading states) +├── transformations/ # Custom field transforms (full-date, array) +└── utils/ # Shared utilities +``` + +### Data Flow + +Requests go through a WarpDrive `RequestManager` pipeline: + +``` +Request → AuthHandler → BrnApiHandler → Fetch → Cache + (token) (REST→JSON:API) +``` + +Schemas in `app/schemas/` define all model types declaratively — no class-based `@attr` models. ## Prerequisites -You will need the following things properly installed on your computer. +- [Node.js](https://nodejs.org/) >= 22 (managed via [Volta](https://volta.sh/)) +- [Yarn](https://yarnpkg.com/) 1.x +- [Watchman](https://facebook.github.io/watchman/docs/install.html) +- [Google Chrome](https://google.com/chrome/) (for tests) + +## Getting Started + +```bash +# Install Volta (manages Node & Yarn versions automatically) +curl https://get.volta.sh | bash + +# Clone and install +git clone https://github.com/Brain-up/brn.git +cd brn/frontend +yarn install +``` + +## Development + +| Command | Description | +|---------|-------------| +| `yarn local` | Dev server with local API (`localhost:8081`) | +| `yarn remote` | Dev server with production API (`brainup.site`) | +| `yarn mirage` | Dev server with mocked API (no backend needed) | +| `yarn develop` | Dev server with Firebase dev environment | + +App runs at **http://localhost:4200**. -* [Git](https://git-scm.com/) -* [Node.js](https://nodejs.org/) (>= 22) -* [Yarn](https://yarnpkg.com/) (1.x) -* [Ember CLI](https://ember-cli.com/) -* [Google Chrome](https://google.com/chrome/) +### Test Accounts (on [brainup.site](https://brainup.site)) -## Installation +| Role | Email | Password | +|------|-------|----------| +| User | `default@default.ru` | `password` | +| Specialist | `default2@default.ru` | `password` | -* install [volta.sh](https://volta.sh/) -* install [watchman](https://facebook.github.io/watchman/docs/install.html) -* `git clone ` this repository -* `cd brn/frontend` -* `yarn install` +## Testing -## Running / Development +```bash +yarn test # Lint + tests + coverage +yarn test:ember # Ember tests only +yarn test:coverage # Generate coverage report (open coverage/index.html) +ember test --server # Watch mode +``` -* `yarn local` starts DEV incremental build pointed to localhost:8081 as API -* `yarn remote` starts DEV build pointing to production BE +## Linting -* Visit your app at [http://localhost:4200](http://localhost:4200). -* Visit your tests at [http://localhost:4200/tests](http://localhost:4200/tests). +```bash +yarn lint # Run all linters +yarn lint:js # ESLint +yarn lint:hbs # Template lint +yarn lint:fix # Auto-fix all +``` -### Running Tests +Pre-commit hooks (Husky + lint-staged) automatically format and lint staged files. -* `ember test` -* `ember test --server` +## Building -#### Test coverage report -* `yarn test:coverage` -* open `./coverage/index.html` to see detailed report +```bash +yarn build # Production build (minified, fingerprinted, PurgeCSS) +``` -### Linting +## Key Routes -* `yarn lint:hbs` -* `yarn lint:js` -* `yarn lint:js --fix` +| Path | Description | +|------|-------------| +| `/groups` | Exercise category listing | +| `/groups/:id/series/:id/subgroup/:id/exercise/:id/task/:id` | Full exercise flow | +| `/login` | Authentication | +| `/registration` | User sign-up | +| `/profile` | Account settings | +| `/profile/statistics` | Progress tracking & charts | +| `/contributors` | Open-source contributors | -### Building +## License -* `ember build` (development) -* `ember build --environment production` (production) +[CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) From d7df310812fde91212fc90596e6c7dae2ea5d00f Mon Sep 17 00:00:00 2001 From: Alex Kanunnikov Date: Sun, 1 Mar 2026 21:49:11 +0000 Subject: [PATCH 2/4] Fix review findings and update root README - Fix frontend README: correct component count (30+), schema count (15), TypeScript description, route param names, proxy URL - Fix package.json: update license to CC0-1.0, add real description and repo URL - Rewrite root README: clean structure, accurate tech stack, quick start guide, contributing section, resource links Co-Authored-By: Claude Opus 4.6 --- README.md | 325 +++++++++++++++++++----------------------- frontend/README.md | 10 +- frontend/package.json | 6 +- 3 files changed, 154 insertions(+), 187 deletions(-) diff --git a/README.md b/README.md index 2c9f6aa4e..4b90ad765 100644 --- a/README.md +++ b/README.md @@ -1,194 +1,161 @@ +# Brain Up + [![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/Brain-up/brn) +[![GitHub Stars](https://img.shields.io/github/stars/Brain-up/brn?style=flat-square)](https://github.com/Brain-up/brn) +[![License: CC0-1.0](https://img.shields.io/badge/License-CC0_1.0-lightgrey.svg?style=flat-square)](https://creativecommons.org/publicdomain/zero/1.0/) +[![Website](https://img.shields.io/website?url=https%3A%2F%2Fbrainup.site&style=flat-square&label=brainup.site)](https://brainup.site) + +**[Brain Up](https://brainup.site)** is a web application for auditory training, designed to help people with central auditory processing deficits (with or without hearing loss) improve their listening skills. It targets children (7+), adults, and elderly users — including cochlear implant and hearing aid wearers — through progressive series of audio exercises. + +> **Try it now:** https://brainup.site +> Test user: `default@default.ru` / `password` | Test specialist: `default2@default.ru` / `password` + +--- + +## Project Structure -# Brain Up! -This project is a web-application being developed to support people with a deficit in their central auditory skills with or without hearing loss, i.e. users of cochlear implant or hearing aids. Intended to be used by children older than 7 years, adults, elderly subjects; anyone who wants to improve their auditory skills, training their brain to improve the understanding of what is heard. -It is projected to contain several series of media exercises, which should be added incrementally. - -Our current version is here : https://brainup.site (test user: default@default.ru/password, test specialist: default2@default.ru/password ). -Now you as a user can register and start doing exercises. - -Very useful schema of platform structure and features: https://github.com/Brain-up/brn/wiki/Some-platform-organization-description - -Our road map https://github.com/Brain-up/brn/blob/master/roadmap.md. -Product Vision: [https://github.com/Brain-up/brn/wiki/Product-Vision](https://github.com/Brain-up/brn/wiki/BRN:-Product-Vision). - -## SCIENTIFIC SOURCES -- Additional description with links to analogous applications: https://docs.google.com/document/d/1UKPE9ykj16JG6FZKoxqCoXI6ehWRhyXZnDNxPcaFLWQ/edit -- Scientific basis of the project: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6417420/ - -## Published ARTICLES about our project -- https://wearecommunity.io/communities/community-platform/articles/753 01.12.2020 russian -- https://habr.com/ru/company/epam_systems/blog/530824 01.12.2020 - -Closed for public: -- https://aw.club/global/en/blog/volunteer/brain-up?utm_source=telegram&utm_medium=social&utm_campaign=ongoing 11.08.2022 (russian, english) will be fixed soon -- https://anywhere.epam.com/volunteer/pages-1/brainApp.html (will be fixed soon) 05.05.2020 - -Only for Epamers: -- https://info.epam.com/content/infoepam/topics/locations/russia/articles/2020/may/pro-bono-volunteers_ru.html -- https://info.epam.com/topics/global/industries/articles/2020/jul/brain-up_en.html - -## WE ARE LOOKING FOR -1. Front-end developers: Ember, Angular. -2. Server-side developers: Kotlin and Java. Components, REST and algorithms. -3. IoS developers. -4. Android developers. -5. DevOps: Continuous integration and delivery. -6. UX: Creative designers for UX research and prototype testing. Your ideas how to improve user retention are welcome. -7. Paintest: for creation pictures for exercises. -8. Sign language specialist to create/improve content. -9. QA engineers. -10. Russian-speech specialists to help us with content. -11. English-speech specialists to help us with content. - -Join us! Learn something new, try your skills, prove yourself, get experience and get ahead! - -## HOW TO JOIN? -Project on Epam Plus (for Epamers only): https://plus.epam.com/projects/21598/overview -You can write directly in Telegram to Elena Moshnikova (project founder and tech lead) [https://t.me/ElenaBrainUp](https://t.me/ElenaBrainUp) -or to project email [brainupspbproject@gmail.com](mailto:brainupspbproject@gmail.com) describing your interests or any questions you may have. -Also we have project chats: -dev team Telegram chat: https://t.me/+R-6ThlxgP5QyZmMy -QA team Telegram chat: ask Elena -Autotest Python team chat: ask Elena - -## TOOLS WE USE -- Back-end: KOTLIN + Spring boot. Rest api as integration layer. -- Front-end : TBD - Ember, Angular. -- DB: Postgres13. -- TestContainers for running integration tests. - -# GETTING STARTED! -## Resources: -### Documentation -https://github.com/Brain-up/brn/wiki (old Epam resourse https://awclub.atlassian.net/wiki/spaces/EPMLABSBRN/overview) -### Product Vision: -https://github.com/Brain-up/brn/wiki/BRN:-Product-Vision (old one https://awclub.atlassian.net/wiki/spaces/EPMLABSBRN/pages/2130224/BRN+Product+Vision) -(old one RoadMap: https://awclub.atlassian.net/wiki/spaces/EPMLABSBRN/pages/2130452/Roadmap) -### Project Issues -https://github.com/Brain-up/brn/issues -### Coding standards -https://github.com/Brain-up/brn/wiki/Coding-Standards - -## Development: - -### FE Development prerequisites -1. FrontEnd: Install node v12 or above https://nodejs.org/en/download/ -2. FrontEnd: Install yarn 1.19 or above https://yarnpkg.com/lang/en/docs/install -3. FrontEnd: In order to make any commit you need Husky dependency be installed (you can use frontend build to get it) -4. BackEnd: Install Docker https://hub.docker.com/search/?type=edition&offering=community -5. BackEnd: Idea - -### Start Front Angular Part - admin application -Go to location where the project is download for example C:\brn\brn\frontend-angular - -📄 [See here](./frontend-angular/README.md) - -### Start Front Ember Part - user application -📄 [See here](./frontend/README.md) - -### Database running: -1. Install docker to your machine. -The project uses postgres 11.5. [Documentation](https://www.postgresql.org/docs/11/index.html) -Currently for local development we use [postgres docker image](https://hub.docker.com/_/postgres) -To install docker use: -* [on windows](https://docs.docker.com/docker-for-windows/install/) -* [on mac](https://docs.docker.com/docker-for-mac/install/) -* [on ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/) -* [debian](https://docs.docker.com/install/linux/docker-ce/debian/) -* [centos](https://docs.docker.com/install/linux/docker-ce/centos/) - -2.1 To run docker db image use the following command: -* on linux\windows: ``` -docker run --name postgres_dev -d -p 5432:5432 -e POSTGRES_DB=brn -e POSTGRES_PASSWORD=$PG_PASSWORD -e POSTGRES_USER=$PG_USER postgres:13 +brn/ +├── frontend/ # User-facing SPA (Ember.js / TypeScript) +├── frontend-angular/ # Admin panel (Angular) +├── src/ # Backend API (Kotlin / Spring Boot) +├── api-contract/ # REST API contract (RAML) +├── docker-compose.yml # Full-stack local setup +└── .github/workflows/ # CI/CD pipelines ``` -`$PG_PASSWORD` and `$PG_USER` are environment variables and could be replaced directly or added to your operating system. -[how to add in win10](https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10). -2.2 Alternatively, you can just replace the variables by "admin", the default user and password for development: -```bash -docker run --name postgres_dev -d -p 5432:5432 -e POSTGRES_DB=brn -e POSTGRES_PASSWORD=admin -e POSTGRES_USER=admin postgres:13 -``` +## Tech Stack + +| Layer | Technology | +|-------|------------| +| **Backend** | Kotlin + Spring Boot, REST API | +| **Frontend (user)** | Ember.js 4.12 (Octane), TypeScript, Tailwind CSS | +| **Frontend (admin)** | Angular | +| **Database** | PostgreSQL 13 | +| **Auth** | Firebase | +| **CI/CD** | GitHub Actions, Docker | +| **Testing** | JUnit + TestContainers (BE), QUnit + Mirage (FE) | + +## Quick Start -### Back-end Kotlin Part: -1. Run command 'gradle build' from main project folder to build project with tests. -2. Application.kt is the main class to run application from Idea for example. -3. Get Postman Collection from [https://www.postman.com/koylubaevNT/workspace/brainup/collection/2686902-d91ba307-e131-4d4f-a308-0a272e063c95 and environment from https://www.postman.com/koylubaevNT/workspace/brainup/environment/2686902-95b2c495-82a1-4244-83c7-dad7f8efebd7](https://brnteam.postman.co/workspace/My-Workspace~d7a4e69a-0ba8-4c56-8fc0-4e27e1998f7c/collection/2464717-96455e8c-ba11-49ed-a299-5c1b77b31db8?action=share&creator=2464717). -You can directly login on www.brainup.site with some user, for example default2@default.ru / password, than use his token in postamn in Authorization tab use Bearer Token and put here yours. -4. Make post request from "Firebase" folder "Get Authorization Token" using credentials. -5. Then you can call all other end-points from this Postman collection -end-point specification is here: https://github.com/Brain-up/brn/blob/master/api-contract/api.raml -6. use https://brainup.site/admin/swagger +### Prerequisites -Note that if you are using IntelliJ, you may want to use version 2019.2 and later to avoid issues with new kotlin plugin. +- [Docker](https://docs.docker.com/get-docker/) +- [Node.js](https://nodejs.org/) >= 22 (via [Volta](https://volta.sh/)) — for frontend +- [JDK 17+](https://adoptium.net/) — for backend +- [Yarn](https://yarnpkg.com/) 1.x — for frontend -#### Useful Postman scripts: -- [Script](./postman_scripts/generate_month_history.js) to generate month tasks statistics (you can use it with `brnlogin` request in `Test` tab) +### Run Everything with Docker Compose -### Deploy Application USING DOCKER COMPOSE: -(back-end part and front-end parts, but it is rather slow. it is better to use GitPod) -From console, from project's folder, execute: ```bash +git clone https://github.com/Brain-up/brn.git +cd brn docker compose up --build ``` -Alternatively, use daemon mode (no console output): + +- **API + Swagger:** http://localhost:8081/api/swagger-ui.html +- **Public Swagger:** https://brainup.site/admin/swagger + +### Run Frontend Only + ```bash -docker compose up --build -d +cd frontend +yarn install +yarn local # → localhost:4200, proxies API to localhost:8081 +yarn mirage # → localhost:4200, mocked API (no backend needed) ``` -Local REST API will be accessible at http://localhost:8081/api/swagger-ui.html -Public is always here https://brainup.site/admin/swagger (login with ADMIN role user) - -docker useful command: -```shell -docker ps -a # for show all containers -docker stop idContainer # for stop running container -docker rm $(docker ps -a -q) # Remove all stopped containers + +See [frontend/README.md](./frontend/README.md) for full details. + +### Run Backend Only + +```bash +# Start PostgreSQL +docker run --name postgres_dev -d -p 5432:5432 \ + -e POSTGRES_DB=brn -e POSTGRES_PASSWORD=admin -e POSTGRES_USER=admin postgres:13 + +# Build and run +./gradlew build +# Run Application.kt from your IDE ``` -## Development tips: -1. Get a task assigned in JIRA (for epamers) or issue (https://github.com/Brain-up/brn/issues) you chose and discussed it with @ElenaSpb, send your githubnick to her. -2. Create branch from dev with the codename of your task, i.e. #GitHub_TaskNumber#. -3. Implement your task, do not forget to write tests. Remember to follow project's coding standards: https://github.com/Brain-up/brn/wiki/Coding-Standards. -4. Create pull request with task name and description about what was done. -5. Notify the team in our skype chat and wait for reviews. At least one reviewer is necessary, but more can be added in a case by case basis. -6. The task gets merged by a project maintainer. -7. check that build job on jenkins passes successfully. -8. Before load config files check them with https://orfogrammka.ru/ service. -9. Integration tests does not run in build process, it can/should be run locally with run job verification/integrationTests. - -### Code style: -1. Please refer for details to kb resources: https://github.com/Brain-up/brn/wiki/Coding-Standards -2. Always use Ctrl+Alt+L in IDEA to update code formatting before committing! -3. Use `gradlew ktlint` command to check code style. If this task fails, the related report with error details can be found in the 'build\reports\ktlint' folder. -4. It is also possible to use `gradlew ktlintFormat` command to fix code style errors automatically. -5. Please note that if `gradlew ktlint` task fails, project build will fail also. -6. For `api.raml` validation, you can use [Api Designer] (https://rawgit.com/mulesoft/api-designer/v0.4.2/dist/index.html). - -### Kotlin input dto validation: -https://github.com/Brain-up/brn/wiki/Kotlin-request-dto-validation-with-annotations - -### Flyway scripts naming -use `V2yearmonthday_taskNumber` -for example `V220210804_899`. - -### Branches: -Use format '#GitHub_TaskNumber-# issue description' or 'Merge description'. Issue number must be in range [0-1999] - -### Sonar: -1. https://sonarcloud.io/code?id=Brain-up_brn our project sonar cloud. -2. To view test coverage locally - 2.1 use jacoco gradle task locally `jacocoTestReport` - 2.2 command line: `gradle jacocoTestReport` -3. Pay attention that main local metric would be a little bit different from the one in Sonar cloud. - -### Thanks companies for support -- EPAM for Jira/Confluence, test instance and Jenkins, for contribution support program. -- JetBrains for IDEA licenses -- Selectel for public instance -- GitHub for code place and actions where we run CI/CD -- Yandex for Yandex Speech Kit service and free account to use it - -### Thanks all volunteers for contribution! - -### License -CC0 1.0 Universal https://joinup.ec.europa.eu/licence/cc0-10-universal-cc0-10-public-domain-dedication + +### Run Admin Panel + +See [frontend-angular/README.md](./frontend-angular/README.md). + +--- + +## Resources + +| Resource | Link | +|----------|------| +| Documentation (Wiki) | https://github.com/Brain-up/brn/wiki | +| Product Vision | [Product Vision](https://github.com/Brain-up/brn/wiki/BRN:-Product-Vision) | +| Platform Structure | [Platform Schema](https://github.com/Brain-up/brn/wiki/Some-platform-organization-description) | +| Roadmap | [roadmap.md](./roadmap.md) | +| Issues | https://github.com/Brain-up/brn/issues | +| Coding Standards | [Coding Standards](https://github.com/Brain-up/brn/wiki/Coding-Standards) | +| Sonar | https://sonarcloud.io/code?id=Brain-up_brn | + +### Scientific Background + +- [Scientific basis (PubMed)](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6417420/) +- [Analogous applications overview](https://docs.google.com/document/d/1UKPE9ykj16JG6FZKoxqCoXI6ehWRhyXZnDNxPcaFLWQ/edit) + +### Articles About the Project + +- [WeAreCommunity (2020)](https://wearecommunity.io/communities/community-platform/articles/753) +- [Habr (2020)](https://habr.com/ru/company/epam_systems/blog/530824) + +--- + +## Contributing + +We welcome contributors of all skill levels! + +### How to Join + +- **Telegram:** Contact Elena Moshnikova (project founder) — [https://t.me/ElenaBrainUp](https://t.me/ElenaBrainUp) +- **Email:** [brainupspbproject@gmail.com](mailto:brainupspbproject@gmail.com) +- **Dev chat:** https://t.me/+R-6ThlxgP5QyZmMy + +### We Are Looking For + +- **Frontend developers** (Ember.js, Angular) +- **Backend developers** (Kotlin, Java) +- **Mobile developers** (iOS, Android) +- **DevOps engineers** (CI/CD, Docker) +- **UX designers** (research, prototyping, user retention) +- **QA engineers** (manual and automation) +- **Content specialists** (Russian, English, sign language) +- **Artists** for exercise illustrations + +### Development Workflow + +1. Pick an [issue](https://github.com/Brain-up/brn/issues) and discuss with [@ElenaSpb](https://github.com/ElenaSpb) +2. Create a branch: `#issue_number-short-description` +3. Implement with tests, follow [coding standards](https://github.com/Brain-up/brn/wiki/Coding-Standards) +4. Open a pull request — at least one review required +5. Maintainer merges after approval + +### Code Style + +- **Backend:** Run `./gradlew ktlint` before committing. Auto-fix with `./gradlew ktlintFormat` +- **Frontend:** Pre-commit hooks handle formatting automatically (Husky + lint-staged) +- **Flyway migrations:** Name as `V2yearmonthday_taskNumber` (e.g. `V220210804_899`) + +--- + +## Thanks + +- **EPAM** — infrastructure support and volunteer program +- **JetBrains** — IDE licenses +- **Selectel** — hosting +- **GitHub** — code hosting and CI/CD +- **Yandex** — Speech Kit service + +And thanks to all [volunteers](https://brainup.site/contributors) for their contributions! + +## License + +[CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) — public domain dedication. diff --git a/frontend/README.md b/frontend/README.md index 5c18c93d3..1e0d9ec76 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -15,7 +15,7 @@ This directory contains the **frontend** application — an Ember.js Octane SPA | Layer | Technology | |-------|------------| | **Framework** | [Ember.js](https://emberjs.com/) 4.12 (Octane) | -| **Language** | TypeScript 5.9 (strict mode) | +| **Language** | TypeScript 5.9 (strict checks enabled) | | **Data** | [WarpDrive](https://github.com/emberjs/data) 5.8.1 — schema-driven, replaces ember-data | | **Styling** | Tailwind CSS + PostCSS + PurgeCSS | | **Auth** | Firebase + ember-simple-auth | @@ -30,7 +30,7 @@ This directory contains the **frontend** application — an Ember.js Octane SPA ``` app/ ├── authenticators/ # Firebase & OAuth2 auth strategies -├── components/ # 36+ Glimmer components (task-player, audio-player, skeleton, ui/...) +├── components/ # 30+ Glimmer components (task-player, audio-player, skeleton, ui/...) ├── controllers/ # Route-specific state ├── handlers/ # WarpDrive request pipeline handlers │ ├── auth-handler # → injects Firebase auth tokens @@ -38,7 +38,7 @@ app/ ├── helpers/ # Template helpers ├── modifiers/ # Glimmer element modifiers ├── routes/ # Route definitions & model hooks -├── schemas/ # WarpDrive model schemas (16 types) +├── schemas/ # WarpDrive model schemas (15 types) ├── services/ # Singletons (store, audio, network, stats, timers, ...) ├── styles/ # Tailwind config & app CSS ├── templates/ # Handlebars templates (incl. skeleton loading states) @@ -81,7 +81,7 @@ yarn install | Command | Description | |---------|-------------| | `yarn local` | Dev server with local API (`localhost:8081`) | -| `yarn remote` | Dev server with production API (`brainup.site`) | +| `yarn remote` | Dev server with production API (`www.brainup.site`) | | `yarn mirage` | Dev server with mocked API (no backend needed) | | `yarn develop` | Dev server with Firebase dev environment | @@ -125,7 +125,7 @@ yarn build # Production build (minified, fingerprinted, PurgeCSS) | Path | Description | |------|-------------| | `/groups` | Exercise category listing | -| `/groups/:id/series/:id/subgroup/:id/exercise/:id/task/:id` | Full exercise flow | +| `/groups/:group_id/series/:series_id/subgroup/:subgroup_id/exercise/:exercise_id/task/:task_id` | Full exercise flow | | `/login` | Authentication | | `/registration` | User sign-up | | `/profile` | Account settings | diff --git a/frontend/package.json b/frontend/package.json index 57f8b07fa..f85071b30 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -2,9 +2,9 @@ "name": "brn", "version": "0.0.0", "private": true, - "description": "Small description for brn goes here", - "repository": "", - "license": "MIT", + "description": "Web application for auditory training — frontend (Ember.js)", + "repository": "https://github.com/Brain-up/brn", + "license": "CC0-1.0", "author": "", "directories": { "doc": "doc", From d2b1f7547727d6e47845d65d7a995c3f1b55c423 Mon Sep 17 00:00:00 2001 From: Alex Kanunnikov Date: Sun, 1 Mar 2026 21:51:31 +0000 Subject: [PATCH 3/4] Fix root README review findings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix Gradle lint command: ktlint → ktlintCheck - Add Angular testing stack (Jasmine + Karma) to tech table Co-Authored-By: Claude Opus 4.6 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4b90ad765..197719198 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ brn/ | **Database** | PostgreSQL 13 | | **Auth** | Firebase | | **CI/CD** | GitHub Actions, Docker | -| **Testing** | JUnit + TestContainers (BE), QUnit + Mirage (FE) | +| **Testing** | JUnit + TestContainers (BE), QUnit + Mirage (Ember FE), Jasmine + Karma (Angular admin) | ## Quick Start @@ -140,7 +140,7 @@ We welcome contributors of all skill levels! ### Code Style -- **Backend:** Run `./gradlew ktlint` before committing. Auto-fix with `./gradlew ktlintFormat` +- **Backend:** Run `./gradlew ktlintCheck` before committing. Auto-fix with `./gradlew ktlintFormat` - **Frontend:** Pre-commit hooks handle formatting automatically (Husky + lint-staged) - **Flyway migrations:** Name as `V2yearmonthday_taskNumber` (e.g. `V220210804_899`) From 4009c31e392d4bedd2e3601090dc2f5257baf50c Mon Sep 17 00:00:00 2001 From: Alex Kanunnikov Date: Sun, 1 Mar 2026 21:54:24 +0000 Subject: [PATCH 4/4] Restore meaningful info dropped from root README Add back: inspiring call-to-action, Postman collection & scripts, API contract reference, daemon mode flag, ktlint failure/report note, integration test instructions, JaCoCo coverage, Kotlin DTO validation wiki link, orfogrammka.ru content validation, and Swagger login note. Co-Authored-By: Claude Opus 4.6 --- README.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 197719198..358993cb0 100644 --- a/README.md +++ b/README.md @@ -51,10 +51,12 @@ brn/ git clone https://github.com/Brain-up/brn.git cd brn docker compose up --build +# Or in daemon mode (no console output): +docker compose up --build -d ``` - **API + Swagger:** http://localhost:8081/api/swagger-ui.html -- **Public Swagger:** https://brainup.site/admin/swagger +- **Public Swagger:** https://brainup.site/admin/swagger (login with ADMIN role user) ### Run Frontend Only @@ -79,6 +81,10 @@ docker run --name postgres_dev -d -p 5432:5432 \ # Run Application.kt from your IDE ``` +**API testing:** Use the [Postman collection](https://brnteam.postman.co/workspace/My-Workspace~d7a4e69a-0ba8-4c56-8fc0-4e27e1998f7c/collection/2464717-96455e8c-ba11-49ed-a299-5c1b77b31db8?action=share&creator=2464717). Login on brainup.site, then use the Bearer token from your session in Postman's Authorization tab. Endpoint specification: [`api-contract/api.raml`](./api-contract/api.raml). + +Useful Postman scripts: [generate month task statistics](./postman_scripts/generate_month_history.js) (use with `brnlogin` request in the `Test` tab). + ### Run Admin Panel See [frontend-angular/README.md](./frontend-angular/README.md). @@ -95,6 +101,8 @@ See [frontend-angular/README.md](./frontend-angular/README.md). | Roadmap | [roadmap.md](./roadmap.md) | | Issues | https://github.com/Brain-up/brn/issues | | Coding Standards | [Coding Standards](https://github.com/Brain-up/brn/wiki/Coding-Standards) | +| Kotlin DTO Validation | [Request DTO validation with annotations](https://github.com/Brain-up/brn/wiki/Kotlin-request-dto-validation-with-annotations) | +| API Contract | [`api-contract/api.raml`](./api-contract/api.raml) | | Sonar | https://sonarcloud.io/code?id=Brain-up_brn | ### Scientific Background @@ -111,7 +119,7 @@ See [frontend-angular/README.md](./frontend-angular/README.md). ## Contributing -We welcome contributors of all skill levels! +We welcome contributors of all skill levels! Join us — learn something new, try your skills, get experience and get ahead! ### How to Join @@ -140,9 +148,12 @@ We welcome contributors of all skill levels! ### Code Style -- **Backend:** Run `./gradlew ktlintCheck` before committing. Auto-fix with `./gradlew ktlintFormat` +- **Backend:** Run `./gradlew ktlintCheck` before committing (if it fails, the build fails too — check `build/reports/ktlint` for details). Auto-fix with `./gradlew ktlintFormat` - **Frontend:** Pre-commit hooks handle formatting automatically (Husky + lint-staged) - **Flyway migrations:** Name as `V2yearmonthday_taskNumber` (e.g. `V220210804_899`) +- **Content files:** Validate Russian text with [orfogrammka.ru](https://orfogrammka.ru/) before committing +- **Integration tests** don't run in the default build — run them locally with `./gradlew integrationTest` +- **Local test coverage:** Run `./gradlew jacocoTestReport` (note: local metrics may differ slightly from [Sonar](https://sonarcloud.io/code?id=Brain-up_brn)) ---