Beyou — Frontend

A gamified personal-productivity app for habits, goals, routines, tasks, and categories.
One TypeScript codebase, two clients: a React web app and an Expo mobile app.

---

Beyou helps people build better days. You define categories of life, attach habits, goals, tasks, and daily routines, then check them off — earning XP, leveling up, and keeping streaks alive. A diary records how each day actually felt, alongside what got done, a calendar holds the one-off things that belong to a date and reminds you of them, an Ideas board keeps stray thoughts as post-it notes until you know what they are, and a study notebook holds what you are learning, laid out as a roadmap of pages. The app is bilingual (English / Portuguese), themeable, and ships an AI assistant that can act on your account.

Use it at app.beyouweb.com or install the Android app from Google Play. One account works on both.

This repository is the frontend monorepo. It contains both user-facing clients and the shared TypeScript core they have in common. The Spring Boot API lives in a separate Beyou-backend-spring repository.

Highlights

• Two clients, one core — a Vite + React web app and an Expo + React Native mobile app share the same domain types, Redux state, API repositories, validation schemas, themes, and translations.
• Transport-agnostic API layer — @beyou/api defines an HttpClient interface; the web injects an axios adapter and mobile a fetch adapter, so business logic never knows which client it runs in.
• Gamification built in — XP, per-habit levels, streaks, level-up and streak-milestone celebrations, and floating +XP feedback on check-in.
• A new day, briefed — the first dashboard open of a day shows what is still open from yesterday, checkable right there at whatever the late check-in is now worth, next to what today holds. The figures are computed on the server; the LLM only phrases them, so a provider being down costs a sentence and not the panel.
• Focus Mode — a pomodoro timer on today's routine items, with micro-tasks per item that can be pinned to follow you from item to item. Completed cycles are kept per day and show up, with the micro-tasks, on that item's row of the day's routine snapshot.
• Goals as a tree — a goal can sit under another, three levels deep, and a viewer page walks the tree with each goal's progress. Finished or abandoned goals can be archived with their sub-goals and brought back the same way.
• A mood a day, and a diary — a five-point scale plus optional journalling. The dashboard widget marks the day with one tap, through a request that has no field for a note, so it cannot erase what you wrote that morning. Only the diary page's Save button replaces an entry.
• A calendar with reminders: one-off tasks on a date, with an optional time and advance notice, next to each day's routine (and how it went), goal deadlines and mood, in a month or a week view. The web app shows a browser notification at the reminder time while a Beyou tab is open, and the server mails a reminder nobody reacted to within the hour. Completing a task pays XP. An opt-in dashboard widget lists today's tasks. The phone has the calendar and the widget, with reminders by mail only for now.
• An Ideas board for whatever crosses your mind. Type it and press Enter, or press Alt+N on any page of the web app, and it sticks to a free board as a post-it note. Drag notes wherever they make sense, colour them, tidy them into a grid by colour, archive the ones you're done with. When an idea turns out to be something to do, "Make it a task" opens the task form already filled in and the note moves to the archive. The assistant can jot notes down for you and read them back. No XP, on purpose. The phone has the same free board: hold a note to drag it, pinch to zoom.
• A study notebook — a topic is a roadmap board whose nodes open pages of notes, and every page can hold a board of its own. Flashcards come back on a spaced schedule, and a study room answers from your notes and sources (PDFs, links, pasted text) with citations you can open. It asks what you are after before you start, and it can search the web for sources for you. It draws, too: a flow, a map, a cycle, a sequence, layers or a timeline, kept on the page as a block you can adjust with the AI or by hand. On a desktop your notes can sit beside the chat while you ask. The phone has the whole notebook too: the editor, the roadmap as a path, cards, the study room and AI roadmap drafts.
• Study cycles line notebook subjects up in a queue of blocks, the ciclo de estudos people use for exams in Brazil. A subject is a whole topic or any page inside one, so a cycle can rotate between the areas of a single topic; two subjects never overlap. A block asks for some time on a subject or for one concept understood, and when it closes the next one comes up. The notebook opens on today's slice of the queue, with clock times if the day has a start time. A pomodoro on any page under the subject counts toward its block; study away from the timer can be logged by hand. How the week splits between subjects is the server's arithmetic, so the editor's preview is the cycle that gets saved.
• Sign in your way — e-mail and password, Google, or any configured OpenID Connect provider (web only for now). A federated identity is matched by its issuer and subject, never by e-mail, so a new provider reaches an existing account only through a link made from inside it.
• AI assistant — a streaming chat whose tools call the same API the buttons do, so it passes the same ownership checks and validation. It can read your mood levels. It cannot read your journal.
• Theming & i18n as data — two bases × five accent packs as design tokens, plus en/pt resources, shared across both apps.
• Type-safe backend contract — backend types are generated from the OpenAPI spec and guarded against drift in CI.

Repository structure

A Turborepo driven by npm workspaces. Shared packages are consumed source-first (no build step) via Vite and Metro path aliases — only the web app actually builds.

beyou-app/
├── apps/
│   ├── web/        @beyou/web      React 18 + Vite 5 + Tailwind 3 (dev on :3000)
│   └── mobile/     @beyou/mobile   Expo SDK 56 + React Native 0.85 + Expo Router + NativeWind
└── packages/
    ├── types/      @beyou/types        Shared domain types (habit, goal, routine, task, …)
    ├── theme/      @beyou/theme         2 bases × 5 accent packs as design tokens
    ├── i18n/       @beyou/i18n          English + Portuguese translation resources
    ├── state/      @beyou/state         Redux Toolkit slices + root reducer
    ├── api/        @beyou/api           Transport-agnostic HTTP client + API repositories
    ├── validation/ @beyou/validation    Zod schemas for every form
    ├── icons/      @beyou/icons         Platform-neutral icon registry + bilingual search
    └── contracts/  @beyou/contracts     Backend types generated from OpenAPI (drift-gated)

Package	Responsibility
@beyou/types	Plain TypeScript types for every domain entity and DTO.
@beyou/theme	The theme model as colour tokens: a light and a dark base × five accent packs (beyou, amethyst, sunset, forest, cyber).
@beyou/i18n	en / pt translation bundles used by both clients.
@beyou/state	Redux Toolkit slices (categories, habits, goals, routines, tasks, focus, mood, notebook, study cycles, Ideas notes, profile, celebrations…) and the shared root reducer. Also the pure logic both clients share: gamification, sorting, date helpers, mood statistics, the calendar's month and week grids and how a fetched overview takes a local write, the Daily Briefing's open/resolve rules, prose poll and goal pace wording, the notebook's status fan-out and roadmap-as-path levels, its re-read after the assistant changes a board, and the page document's block-by-block merge and save loop (DocumentSync) with what both notebook editors do to a document outside BlockNote (codeLanguages, editorDocument), the flashcard review queue, how a study cycle block reads on screen and where a logged session would land (studyCycleView), which pages a cycle may take as subjects and why the rest are closed (studyCycleSubjects), the rule that "Focus 25" never replaces a running pomodoro, the Ideas board's drop and "make it a task" rules and its note colours (quickNote), and the assistant's tool registry (which tool is a quiet read, and which screen a write links to).
@beyou/api	The HttpClient interface and all API repositories. Adapters are supplied by each app at startup.
@beyou/validation	Zod schemas (auth, habit, goal, task, category, routine, schedule, profile) reused by both web and mobile forms.
@beyou/icons	The icon registry both pickers use, with bilingual search and recents. Each app supplies only the renderer.
@beyou/contracts	TypeScript types generated from the backend's OpenAPI 3.1 spec, with a CI drift gate.

Tech stack

Area	Web (@beyou/web)	Mobile (@beyou/mobile)
Framework	React 18, Vite 5	React 19, React Native 0.85, Expo SDK 56
Routing	react-router-dom v6	Expo Router
Styling	Tailwind CSS 3 + tailwind-merge	NativeWind v4
State	Redux Toolkit + redux-persist	Redux Toolkit
Forms	react-hook-form + Zod	react-hook-form + Zod
HTTP	axios adapter	fetch adapter
Notebook editor	BlockNote 0.55 on Mantine 8 (Mantine 9 needs React 19)	Read-only native block renderer, no WebView
Notebook board	React Flow (@xyflow/react), with "Tidy up" laying nodes on a three-to-a-row grid	The board read as a path, level by level
Notebook diagrams	SVG drawn from the shared layoutDiagram scene (@beyou/state)	The same scene through react-native-svg
Ideas board	React Flow with sticky-note nodes; Alt+N captures from any page	A free board on PanResponder (no gesture library): hold a note to drag it, pinch to zoom
Tests	Vitest + Testing Library	Jest (jest-expo) + Testing Library

Prerequisites

• Node.js ≥ 20 and npm 11.9.0 (the repo pins packageManager).
• For mobile: the Expo toolchain (installed via the workspace) plus the Expo Go app or an Android/iOS simulator.
• The Beyou backend running locally (or reachable on your network) at http://localhost:8099/api/v1. See the Beyou-backend-spring repo.

Getting started

# 1. Clone and install (a single install at the root covers every workspace)
git clone https://github.com/AndDev741/Beyou-Frontend.git
cd Beyou-Frontend
npm install

# 2. Configure the web app's environment
cp apps/web/.env.example apps/web/.env

apps/web/.env:

VITE_API_URL=http://localhost:8099   # backend base (the /api/v1 suffix is added per request)
VITE_APP_URL=http://localhost:3000   # this app's own URL (used by the Google OAuth flow)
# VITE_GOOGLE_CLIENT_ID=...          # required only for Google sign-in

Note

The mobile app reads EXPO_PUBLIC_API_URL (defaults to http://localhost:8099/api/v1). When testing on a physical device, point it at your machine's LAN address rather than localhost.

Run the web app

npm run web          # Vite dev server on http://localhost:3000

Run the mobile app

npm --workspace @beyou/mobile run start     # Expo dev server (scan the QR with Expo Go)
npm --workspace @beyou/mobile run android   # open on Android
npm --workspace @beyou/mobile run ios       # open on iOS

Common commands

Root scripts run across the whole monorepo through Turborepo:

Command	What it does
npm run build	Build every buildable workspace (the web app's production bundle).
npm test	Run all test suites (web + packages via Vitest, mobile via Jest).
npm run typecheck	Type-check every workspace.
npm run lint	Lint every workspace.
npm run web	Start the web dev server.

Per-workspace scripts are available too, e.g.:

npm --workspace @beyou/web run build         # production web build
npm --workspace @beyou/web run test:watch    # watch-mode web tests
npm --workspace @beyou/contracts run check   # backend contract drift gate

How the apps share code

              ┌─────────────────────────────────────────────┐
              │  packages/  (source-first, no build step)    │
              │  types · theme · i18n · state · validation   │
              │  api (HttpClient interface + repositories)   │
              └───────────────┬──────────────┬───────────────┘
                              │              │
            axios adapter ────┤              ├──── fetch adapter
                              │              │
                     ┌────────▼─────┐  ┌─────▼────────┐
                     │  apps/web    │  │ apps/mobile  │
                     │  React 18    │  │  Expo / RN   │
                     └──────────────┘  └──────────────┘

@beyou/api exposes setHttpClient(); each app registers its adapter at startup, so repository code (getHabits, createGoal, checkItem, …) stays identical across platforms. The backend wire contract is generated into @beyou/contracts from OpenAPI and verified by npm --workspace @beyou/contracts run check.

Testing & CI

• Web & packages use Vitest with Testing Library.
• Mobile uses Jest via jest-expo and Testing Library for React Native.
• GitHub Actions (.github/workflows/) run on every push and PR to main: typecheck → build → test → contract drift check → dependency audit, then the Playwright e2e suite against the full stack, plus a weekly CodeQL security scan. Once those pass on main, the web build deploys to Cloudflare as the static Worker beyou-web at app.beyouweb.com (apps/web/wrangler.jsonc, headers in apps/web/public/_headers). A merge that touches apps/mobile or a shared package also builds the Android App Bundle and publishes it to the Google Play open testing track (mobile-aab.yml; other tracks by manual dispatch).

npm test                                    # everything
npm --workspace @beyou/web run test         # web only
npm --workspace @beyou/mobile run test      # mobile only

Important

Mobile contributors: this workspace intentionally ships two React versions side by side — React 19 for apps/mobile (an Expo SDK 56 requirement) and React 18 for the web app. The root package.json overrides and apps/mobile/metro.config.js keep them isolated. Do not run npm dedupe — it collapses the two installs and breaks the mobile bundler. See apps/mobile/AGENTS.md for the full rationale and the Expo Router / NativeWind conventions.

Related repositories

Repo	Purpose
Beyou-backend-spring	Spring Boot API (PostgreSQL, JWT + Google OAuth, the AI assistant) on port 8099.
Beyou-e2e-tests	Playwright end-to-end suite driving the full stack.
Beyou-dev-env	Docker Compose orchestration for local development.
Beyou-arch-design	OpenAPI specs and architecture / design documentation.