How alchemistofweb/wishlists_frontend works
1. Overall shape
- This repository is a frontend-only React SPA for a wishlist/friends app.
- The architecture is centered in frontend/src, with a thin separation between routing/layout, domain pages, shared UI components, and a REST API client layer.
2. Runtime and build
- The app uses Vite + TypeScript + React.
- Key entry/build files are frontend/src/main.tsx, frontend/index.html, frontend/vite.config.ts, and frontend/package.json.
- Deployment/local run is containerized via docker-compose.frontend.yml and frontend/Dockerfile, or run directly with npm run dev.
3. Application bootstrap
- frontend/src/main.tsx is the entry point that mounts the React tree.
- frontend/src/App.tsx appears to assemble the top-level application shell, likely wiring providers and the router.
4. Routing and access control
- Route definitions are centralized in frontend/src/router/router.tsx.
- Auth-protected navigation is handled by frontend/src/components/ProtectedRoute.tsx.
- The route map is domain-oriented: auth pages under frontend/src/pages/auth/, wishlist pages under frontend/src/pages/wishlist/, plus general app pages like DashboardPage.tsx, FriendsPage.tsx, ProfilePage.tsx, and EventsPage.tsx.
5. Layout and shared shell
- frontend/src/layouts/MainLayout.tsx defines the common authenticated app frame.
- Shared navigation is in frontend/src/components/Navbar.tsx.
- This suggests a split between public auth screens and an authenticated layout with persistent chrome.
6. Auth subsystem
- Authentication state is encapsulated in frontend/src/auth/AuthProvider.tsx.
- Utility logic for auth/token handling lives in frontend/src/utils/auth.ts and frontend/src/utils/token.ts.
- Public auth screens are frontend/src/pages/auth/SignInPage.tsx and frontend/src/pages/auth/SignUpPage.tsx.
- The app likely stores tokens locally and uses the auth provider to gate protected routes and populate request headers.
7. API boundary
- All server interaction is isolated under frontend/src/api/.
- client.ts is the shared HTTP client wrapper; feature modules such as auth.ts, users.ts, friends.ts, tags.ts, wishlist.ts, and wishlistItems.ts provide domain-specific requests.
- This creates a clear boundary: UI components/pages do not talk to the backend directly, but through typed API modules.
8. Wishlist domain
- The wishlist feature is the most componentized area.
- Pages are grouped under frontend/src/pages/wishlist/: WishlistPage.tsx, WishlistListPage.tsx, and FriendWishlistPage.tsx.
- Reusable UI pieces live in frontend/src/components/wishlist/, including WishlistItemsGrid.tsx, WishlistItemCard.tsx, WishlistItemForm.tsx, and WishlistEditModal.tsx.
- Data types for this domain are defined in frontend/src/types/wishlist.ts and frontend/src/types/wishlistItem.ts.
9. Other domain pages
- Friends-related UI is in frontend/src/pages/FriendsPage.tsx and likely backed by frontend/src/api/friends.ts and frontend/src/types/friend.ts.
- User/profile views are in frontend/src/pages/ProfilePage.tsx and frontend/src/pages/UserProfilePage.tsx, with frontend/src/api/users.ts and frontend/src/types/user.ts.
- frontend/src/pages/DashboardPage.tsx and frontend/src/pages/EventsPage.tsx serve as higher-level app views.
10. Shared types, constants, and UI rules
- Types are organized by domain in frontend/src/types/.
- App-wide constants live in frontend/src/constants/ (api.ts, http.ts, routes.ts, storage.ts, ui.ts), which keeps route paths, API base settings, storage keys, and UI values out of components.
- This matches the repo rule of avoiding magic numbers/strings in feature code.
11. Data flow
- The typical flow is: route → page → domain component → API module → backend REST service.
- Authentication adds a cross-cutting flow: sign-in/sign-up → token storage → AuthProvider state → ProtectedRoute/MainLayout → authenticated API calls.
- Wishlist editing likely follows the same pattern via modal/form components that submit through api/wishlistItems.ts or api/wishlist.ts.
12. Project boundaries
- The repository contains only the frontend layer; the backend is external to what’s shown here.
- The architecture is intentionally modular within the UI: pages are route-level orchestration, components are reusable presentation blocks, api modules isolate transport, and types/constants keep contracts explicit.
Main entry points: client.ts HTTP client · users.ts users API · auth.ts auth API · wishlist.ts wishlist API
Components 34
Shell & auth
Application bootstrap, routing, layout, and route protection.
- main.tsx · Mounts the React application.
frontend/src/main.tsx - App shell · Assembles top-level providers and routing.
frontend/src/App.tsx - Router · Central route definitions for public and protected screens.
frontend/src/router/router.tsx - Protected route · Blocks unauthenticated access to private areas.
frontend/src/components/ProtectedRoute.tsx - Main layout · Shared frame for signed-in views.
frontend/src/layouts/MainLayout.tsx - Navbar · Persistent top-level navigation for the app.
frontend/src/components/Navbar.tsx - AuthProvider · Holds session/authentication state for the UI.
frontend/src/auth/AuthProvider.tsx
Pages
Route-level screens organized by domain.
- Sign in · User login screen.
frontend/src/pages/auth/SignInPage.tsx - Sign up · User registration screen.
frontend/src/pages/auth/SignUpPage.tsx - Dashboard · High-level landing page after authentication.
frontend/src/pages/DashboardPage.tsx - Friends · Friends overview and related actions.
frontend/src/pages/FriendsPage.tsx - Profile · Signed-in user profile view.
frontend/src/pages/ProfilePage.tsx - User profile · Other-user profile view.
frontend/src/pages/UserProfilePage.tsx - Events · Events or activity-oriented app view.
frontend/src/pages/EventsPage.tsx - Wishlist · Primary wishlist view.
frontend/src/pages/wishlist/WishlistPage.tsx - Lists · Wishlist list management view.
frontend/src/pages/wishlist/WishlistListPage.tsx - Friend wishlist · Wishlist view for a friend or other user.
frontend/src/pages/wishlist/FriendWishlistPage.tsx
Wishlist UI
Reusable wishlist components used by wishlist pages.
- Items grid · Displays wishlist items in a grid layout.
frontend/src/components/wishlist/WishlistItemsGrid.tsx - Item card · Renders a single wishlist item.
frontend/src/components/wishlist/WishlistItemCard.tsx - Item form · Creates or edits a wishlist item.
frontend/src/components/wishlist/WishlistItemForm.tsx - Edit modal · Modal wrapper for wishlist item editing.
frontend/src/components/wishlist/WishlistEditModal.tsx
API layer
REST client wrapper and feature API modules.
- HTTP client · Shared REST client and request configuration.
frontend/src/api/client.ts - auth API · Login and registration requests.
frontend/src/api/auth.ts - users API · User profile and user lookup requests.
frontend/src/api/users.ts - friends API · Friend-related requests.
frontend/src/api/friends.ts - tags API · Tag-related requests.
frontend/src/api/tags.ts - wishlist API · Wishlist collection requests.
frontend/src/api/wishlist.ts - items API · Wishlist item CRUD requests.
frontend/src/api/wishlistItems.ts
Shared contracts
Domain types, constants, and auth/token helpers.
- auth types · Authentication data contracts.
frontend/src/types/auth.ts - user types · User data contracts.
frontend/src/types/user.ts - friend types · Friend data contracts.
frontend/src/types/friend.ts - wishlist types · Wishlist data contracts.
frontend/src/types/wishlist.ts - item types · Wishlist item data contracts.
frontend/src/types/wishlistItem.ts - auth utils · Helpers for auth state and token handling.
frontend/src/utils/auth.ts
Connections 33
- main.tsx → App shell: renders · Application entry mounts the app shell.
- App shell → Router: uses · App shell delegates navigation to the router.
- Router → Protected route: guards · Protected routes require authentication.
- Router → Main layout: wraps · Signed-in routes use the authenticated layout.
- Main layout → Navbar: contains · Layout keeps shared navigation visible.
- App shell → AuthProvider: provides · Auth provider supplies session state to the tree.
- Sign in → auth API: calls · Login screen submits credentials via auth API.
- Sign up → auth API: calls · Registration screen uses auth API.
- auth API → HTTP client: built on · Auth requests use the shared HTTP client.
- users API → HTTP client: built on · User requests use the shared HTTP client.
- friends API → HTTP client: built on · Friend requests use the shared HTTP client.
- tags API → HTTP client: built on · Tag requests use the shared HTTP client.
- wishlist API → HTTP client: built on · Wishlist requests use the shared HTTP client.
- items API → HTTP client: built on · Wishlist item requests use the shared HTTP client.
- AuthProvider → auth utils: uses · Auth provider depends on token/session helpers.
- AuthProvider → auth types: models · Auth state follows auth data contracts.
- Wishlist → Items grid: composes · Primary wishlist page renders item grid UI.
- Wishlist → Edit modal: uses · Edit flow opens the wishlist edit modal.
- Items grid → Item card: contains · Grid arranges individual item cards.
- Edit modal → Item form: contains · Edit modal hosts the item form.
- Item form → items API: submits to · Form persists changes through item API.
- Friend wishlist → wishlist API: loads · Friend wishlist view fetches wishlist data.
- Lists → wishlist API: loads · Wishlist list page queries wishlist collections.
- Friends → friends API: loads · Friends page retrieves friend data.
- Profile → users API: loads · Profile page fetches user data.
- User profile → users API: loads · Other-user profile page fetches user data.
- Dashboard → users API: aggregates · Dashboard likely combines user-related summary data.
- Events → tags API: relates to · Events view may filter or organize by tags.
- wishlist API → wishlist types: uses · Wishlist API is typed by wishlist contracts.
- items API → item types: uses · Item API is typed by item contracts.
- users API → user types: uses · User API is typed by user contracts.
- friends API → friend types: uses · Friend API is typed by friend contracts.
- auth API → auth types: uses · Auth API uses auth contracts.