103 lines
8.2 KiB
Markdown
103 lines
8.2 KiB
Markdown
# System Patterns — Strava Frontend
|
|
|
|
## Architecture (SPA layering)
|
|
|
|
```
|
|
src/
|
|
main.ts - app bootstrap, axios instances, providers
|
|
App.vue - root component
|
|
router/ - vue-router config (lazy pages)
|
|
layouts/ - AppLayout (authenticated shell), AuthLayout, RouterBypass
|
|
pages/ - route components (workouts/, routes/, auth/, preferences/, admin/)
|
|
components/ - reusable UI (navbar/, sidebar/, icons/, app-layout-navigation/)
|
|
stores/ - Pinia stores (user-store, global-store)
|
|
i18n/ - vue-i18n setup + locales/*.json
|
|
services/ - axios helpers, vuestic-ui config (global-config, themes)
|
|
scss/ - global styles, vuestic-sass, icon fonts
|
|
|
|
server/ - SSR Express server (NOT type-checked by vue-tsc, excluded from tsconfig include)
|
|
index.ts - Express app: SSR routes, helpers, port 3001
|
|
template.ts - HTML shell with SEO meta, OG tags, JSON-LD, asset tags
|
|
api.ts - Axios client for backend API (getPublicWorkouts, getPublicWorkout)
|
|
|
|
nginx.conf - Reverse proxy: SSR routes → :3001, everything else → SPA static files
|
|
```
|
|
|
|
Dependency direction: `pages -> components/stores/services`. Pages own business logic; components are presentational. `server/` is standalone (Express, runs via `tsx`).
|
|
|
|
## API access pattern
|
|
|
|
- Two Axios instances created in `src/main.ts`: `axiosAuth` (adds `Authorization: Bearer <token>` from `localStorage` on every request) and `axiosPublic`. Both have a shared response error interceptor: 401 -> `localStorage.clear()` + redirect to `login` route.
|
|
- Instances are provided app-wide: `app.provide('axiosAuth', ...)` / `app.provide('axiosPublic', ...)`. Components consume with `inject('axiosAuth') as AxiosInstance`.
|
|
- Base URL is a hardcoded `HOST` constant in `src/main.ts` (`https://cycle-rider.ru`; localhost variant commented out). All backend paths are under `/api/v0`.
|
|
- Auth check on startup: if `localStorage.token` exists, GET `/api/v0/auth/check`; on failure clear storage.
|
|
|
|
## Data fetching pattern
|
|
|
|
- No central API layer: components/composable `.ts` files (e.g. `src/pages/workouts/components/GetWorkout.ts`) call `axiosAuth.get(url)` directly and map the response into view state.
|
|
- Workout detail data shape: `{ workout, results: [{ timestamp, longitude, latitude, elevation, power, heart_rate, speed }, ...] }` — mapped into Chart.js datasets + map line coordinates.
|
|
|
|
## State management
|
|
|
|
- Pinia with options-style stores. `useUserStore` hydrates from `localStorage` keys `user`, `profile`, `attachments` on store init (no persistence plugin). `useGlobalStore` holds sidebar state.
|
|
- Auth data lives in `localStorage` (keys: `token`, `user`, `profile`, `attachments`).
|
|
|
|
## Routing
|
|
|
|
- History-mode router (`createWebHistory`), all pages lazy-imported.
|
|
- Two layouts: `AppLayout` (sidebar + navbar shell) for authenticated pages; `AuthLayout` for auth pages. Catch-all redirects to `explore` (= `pages/workouts/Feed.vue`).
|
|
- Legacy redirect: `/dashboard` → `explore`.
|
|
- Top-level route `workout_public_item` at `/public/workouts/:id` — NOT nested under AppLayout (accessible without auth, SSR-rendered).
|
|
- No global auth guard — unauthenticated handling is done via the 401 interceptor.
|
|
|
|
## SSR (Server-Side Rendering)
|
|
|
|
- Express server (`server/index.ts`) on port 3001 (env `SSR_PORT`).
|
|
- SSR routes: `GET /` (landing, 302→`/explore` if `token` cookie present), `GET /explore`, `GET /public/workouts/:id`, `GET /routes`, `GET /sitemap.xml`, `GET /robots.txt`, `GET /health`.
|
|
- HTML rendered via `renderTemplate()` from `server/template.ts` — full SEO meta (title, description, canonical, OG, JSON-LD, yandex-verification).
|
|
- Asset tags extracted from `dist/index.html` (hashed filenames); falls back to dev script tag if `dist/` absent.
|
|
- API data fetched server-side via `server/api.ts` (Axios to `VITE_APP_API_URL` || `https://cycle-rider.ru`).
|
|
- Nginx proxies SSR routes to `:3001`; all other paths serve `dist/index.html` (SPA fallback `try_files`).
|
|
- `SSR_BASE_URL` env controls canonical/OG URLs (default `https://cycle-rider.ru`).
|
|
|
|
## Charts & maps
|
|
|
|
- Chart.js via `vue-chartjs` (+ `chartjs-adapter-moment`, `chartjs-plugin-zoom`, `chartjs-chart-geo` for elevation). Chart building lives in `src/pages/workouts/components/*.ts`.
|
|
- Yandex Maps via `vue-yandex-maps` (`createYmaps` with a hardcoded API key in `main.ts`). Route polyline drawn from workout `results` coordinates.
|
|
- **Typing contract (since vue 3.5 strict checks)**: `vue-yandex-maps` `:settings` coordinates must be the `LngLat = [lon, lat, alt?]` tuple type — plain `number[]` refs fail `vue-tsc`. Pattern: `ref<LngLat>([lon, lat])` + `as LngLat` casts in templates (see `pages/routes/Route.vue`, `pages/workouts/components/WorkoutItem.vue`).
|
|
- Custom chart controllers extend `chart.js` controllers (`LineWithLineController` in `LineWithLineChart.ts`); the map-sync plugin is read from `chart.config.plugins` by id — use non-null assertions on `chart.config.data!` (do NOT reintroduce `@ts-ignore`, lint bans it).
|
|
|
|
## Styling
|
|
|
|
- Vuestic UI (config in `src/services/vuestic-ui/global-config.ts`, themes in `themes.ts`, custom icons registered in `icons-config/`).
|
|
- Tailwind CSS with Vuestic CSS variables as color tokens (`--va-primary` etc. in `tailwind.config.js`). Custom font-size tokens: `tag`, `regularSmall/Medium/Large`.
|
|
- Global SCSS in `src/scss/main.scss`; icon fonts in `src/scss/icon-fonts/`.
|
|
|
|
## i18n
|
|
|
|
- `vue-i18n` in composition mode (`legacy: false`), locale and fallback = `ru`. Locales auto-loaded from `src/i18n/locales/*.json` via `import.meta.glob` + `@intlify/unplugin-vue-i18n/vite` plugin.
|
|
|
|
## Error handling
|
|
|
|
- Central axios interceptor logs and re-throws; 401 triggers logout redirect. Components typically use `.then/.catch` chains (callback style, not async/await) — keep the existing style when modifying.
|
|
|
|
## Lint / type-check pipeline
|
|
|
|
- **Flat ESLint config** (`eslint.config.mjs`, eslint 9 + typescript-eslint 8): `tseslint.configs.recommended` + `pluginVue.configs["flat/essential"]`. CRITICAL: the vue flat preset leaves espree as inner parser — the TS parser MUST be attached for `**/*.vue` via `languageOptions.parserOptions.parser` (from the `typescript-eslint` CJS default import).
|
|
- Override style: file-targeted blocks with justifying comments ONLY (no global rule disabling, no inline eslint-disable). Existing exceptions: `src/main.ts` (any/unused — interceptor debt), `src/pages/**/*.vue` (multi-word names), `Logout.vue` (valid-template-root), `workouts/components/WorkoutItem.vue` (no-mutating-props — local-state extraction pending).
|
|
- `ban-ts-comment` is enforced: `@ts-ignore` is not allowed; use `@ts-expect-error` or proper typing (non-null assertions).
|
|
- `no-unused-vars` honors `argsIgnorePattern: "^_"`.
|
|
- `yarn lint` runs `prelint: prettier --write .` — running lint auto-reformats ~30 files; commit the formatting as part of the change.
|
|
|
|
## Build / deploy
|
|
|
|
- Vite 5 build with `vue-tsc 2 --noEmit` type-check in `yarn build`. Dev and Docker both use **yarn v1** (Docker: `node:20-alpine`, `COPY package.json yarn.lock`, `yarn install --frozen-lockfile`).
|
|
- **Docker multi-stage**: Stage 1 (build) — `node:20-alpine`, yarn install, `yarn build`. Stage 2 (runtime) — `node:20-alpine` + nginx, copies `dist/` to nginx html root, copies `server/` + `node_modules/`, CMD runs `npx tsx server/index.ts & nginx -g 'daemon off;'`.
|
|
- `nginx.conf`: SSR proxy for `/explore|/routes|/sitemap.xml|/robots.txt|/public/workouts/|/` → `:3001`; `/assets/` 30d immutable; SPA fallback `try_files $uri /index.html`.
|
|
- `run.sh` launcher for local: `cd /app && npx tsx server/index.ts & nginx -g 'daemon off;'`.
|
|
- `serve -s ./dist` for CI preview (static only, no SSR).
|
|
- `tsx` is in `dependencies` (not devDependencies) — needed in the runtime container.
|
|
- ⚠️ Legacy `package-lock.json` is STALE and unused (Docker no longer copies it) — do not run `npm install` in this repo; removal is a separate cleanup task.
|
|
- Version ceilings (learned the hard way): **vue-tsc 2.x supports TypeScript up to 5.8 — TS 5.9 crashes it** (`Search string not found: "supportedTSExtensions"`); pin `"typescript": "5.8"` no-caret. **sass ≥1.7x latest requires node ≥20.19** — verify local dev node before bumping.
|
|
- yarn 1.22 has no `up` alias — use `yarn upgrade`.
|