# coral0723/loglife architecture

> Architecture diagram of the GitHub repository coral0723/loglife, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coral0723/loglife
- Repository: https://github.com/coral0723/loglife

## Overview

1. **Overall shape**
   LogLife is a Next.js App Router application deployed serverlessly on Vercel. There is no separate backend service; page rendering, authentication callbacks, API routes, and write operations all live inside the same Next.js runtime.

2. **Primary product areas**
   The app is organized around a few user-facing domains: bucket lists on a globe, friends/social features, user profile settings, onboarding, and a landing/login flow. These are reflected directly in `src/components/*`, `src/app/(afterLogin)/*`, and `src/app/(auth)/*`.

3. **Navigation and route boundaries**
   The app uses route groups to separate public auth pages from the authenticated app. After login, the main experience is split into `main`, `friends`, `profile`, and `onboarding`. Public-facing pages also exist for shared bucket pages (`/b/[token]`) and public user profiles (`/u/[username]`).

4. **Modal-driven UX architecture**
   A major architectural choice is the use of parallel and intercepting routes under `src/app/(afterLogin)/@modal`. This lets bucket details, friend dialogs, profile dialogs, and user profile dialogs open as URL-addressable overlays without leaving the current screen.

5. **Server-side data mutation**
   Domain mutations are handled by `src/actions/*` as Server Actions. These are split by domain (`bucketList`, `friend`, `user`, `onboarding`) and are the main path for creating/updating bucket items, friendships, avatars, and onboarding state.

6. **Read and proxy layer**
   Read operations and external-service mediation live in `src/app/api/*` and are consumed by client fetch helpers in `src/api/*`. This includes dashboard metrics, friend widgets, bucket list queries, and proxies to Google Places endpoints such as autocomplete, details, and photo retrieval.

7. **Persistence layer**
   Data is stored in Supabase PostgreSQL and accessed through Prisma. The schema centers on `User`, `Account`, `Session`, `BucketList`, and `Friendship`, with migrations tracked in `prisma/migrations`. Authentication state and app data share the same database.

8. **Authentication and session flow**
   Authentication is implemented with NextAuth v5 in `src/auth.ts` and the callback route at `src/app/api/auth/[...nextauth]/route.ts`. OAuth providers include Google and Kakao. Session state then gates protected routes and powers user-specific data access.

9. **Domain logic and pure helpers**
   Business rules are centralized in `src/lib/*`. This layer contains pure logic for bucket status, visibility, achievement stats, difficulty/excitement matrices, friend relationships, hot-place calculations, username rules, rate limiting, and geospatial helpers such as country centroids and pin generation.

10. **UI composition and state**
    Reusable feature components are grouped by domain in `src/components/*` rather than by technical type. Client-side state is split between TanStack Query for server data, Zustand stores for local interaction state, and small feature stores such as the globe and bucket form stores. The globe view is a distinct visualization subsystem backed by country geo assets in `public/geo`.

11. **Platform-specific experience**
    The app includes PWA support through a service worker (`src/app/sw.ts`) and manifest assets in `public/manifest.json`. It also has an offline overlay, preset avatars, and mobile-oriented navigation, which makes the application feel like an installable product rather than a standard website.

12. **Testing and quality boundaries**
    The repo is heavily testable across layers: Vitest for unit/component tests, Playwright for end-to-end flows, MSW for API mocking, Storybook for isolated UI development, and Chromatic for visual regression. There are even dedicated E2E-only routes under `src/app/(e2e)` to make browser testing deterministic.

13. **Operational and workflow tooling**
    The `.claude`, `.agents`, and `.dev` directories are not product runtime code, but they materially shape development: they encode coding rules, review/test commands, session logging, and accumulated learnings. This suggests a workflow that treats engineering process as part of the repo’s architecture, especially for repeatable QA and AI-assisted maintenance.

Main entry points: [`src/app/(afterLogin)/layout.tsx`](https://github.com/coral0723/loglife/blob/main/src/app/(afterLogin)/layout.tsx) (App routes), [`src/app/api/bucketlists/[id]/route.ts`](https://github.com/coral0723/loglife/blob/main/src/app/api/bucketlists/[id]/route.ts) (Read APIs), [`src/actions/user/actions.ts`](https://github.com/coral0723/loglife/blob/main/src/actions/user/actions.ts) (Server actions), [`src/components/globe/GlobeView.tsx`](https://github.com/coral0723/loglife/blob/main/src/components/globe/GlobeView.tsx) (Globe view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Next.js App"]
  node_src_app_root["App shell<br/>nextjs shell<br/>[layout.tsx]"]
  node_src_app_auth["Auth routes<br/>route group<br/>[page.tsx]"]
  node_src_app_afterlogin["App routes<br/>route group<br/>[layout.tsx]"]
  node_src_app_modal["Modal routes<br/>parallel routes<br/>[default.tsx]"]
  node_src_app_e2e["E2E routes<br/>test routes<br/>[page.tsx]"]
end

subgraph group_ui["UI Components"]
  node_src_store["Client stores<br/>state stores<br/>[globeStore.ts]"]
  node_src_components_globe(("Globe view<br/>visualization UI<br/>[GlobeView.tsx]"))
  node_src_components_bucket["Bucket tools<br/>feature UI"]
  node_src_components_friends["Friends UI<br/>feature UI<br/>[FriendsView.tsx]"]
  node_src_components_dashboard["Dashboard UI<br/>feature UI<br/>[DashboardPanel.tsx]"]
  node_src_components_profile["Profile UI<br/>feature UI"]
  node_src_components_user["Public profile UI<br/>feature UI"]
  node_src_components_landing["Landing UI<br/>marketing UI<br/>[HeroContent.tsx]"]
  node_src_components_shared["Shared UI<br/>base UI<br/>[Button.tsx]"]
end

subgraph group_logic["Domain Logic"]
  node_src_lib_domain["Domain helpers<br/>pure logic<br/>[bucketStatus.ts]"]
end

subgraph group_data["Data Layer"]
  node_src_app_api_auth["Auth callback<br/>api route<br/>[route.ts]"]
  node_src_app_api_data["Read APIs<br/>api routes<br/>[route.ts]"]
  node_src_actions["Server actions<br/>mutation layer<br/>[actions.ts]"]
  node_src_auth["NextAuth setup<br/>auth config<br/>[auth.ts]"]
  node_src_lib_prisma[("Prisma access<br/>db client<br/>[prisma.ts]")]
  node_prisma_schema["DB schema<br/>[schema.prisma]"]
end

subgraph group_workflow["Workflow"]
  node_tests_workflow["Tests<br/>quality stack<br/>[vitest.config.ts]"]
  node_ops_workflow["Dev workflow<br/>tooling rules<br/>[CLAUDE.md]"]
end

node_src_app_root -->|"routes to"| node_src_app_auth
node_src_app_root -->|"hosts"| node_src_app_afterlogin
node_src_app_afterlogin -->|"overlays"| node_src_app_modal
node_src_app_afterlogin -->|"renders"| node_src_components_globe
node_src_app_afterlogin -->|"renders"| node_src_components_dashboard
node_src_app_afterlogin -->|"renders"| node_src_components_friends
node_src_app_afterlogin -->|"renders"| node_src_components_profile
node_src_app_afterlogin -->|"renders"| node_src_components_bucket
node_src_app_auth -->|"uses"| node_src_auth
node_src_app_api_auth -->|"calls"| node_src_auth
node_src_app_api_data -->|"reads/writes"| node_src_lib_prisma
node_src_actions -->|"mutates"| node_src_lib_prisma
node_src_lib_prisma -->|"implements"| node_prisma_schema
node_src_app_api_data -->|"computes"| node_src_lib_domain
node_src_actions -->|"validates"| node_src_lib_domain
node_src_components_globe -->|"uses"| node_src_store
node_src_components_bucket -->|"fetches"| node_src_app_api_data
node_src_components_friends -->|"fetches"| node_src_app_api_data
node_src_components_dashboard -->|"fetches"| node_src_app_api_data
node_src_components_profile -->|"submits"| node_src_actions
node_src_components_user -->|"fetches"| node_src_app_api_data
node_src_components_landing -->|"reuses"| node_src_components_globe
node_tests_workflow -.->|"covers"| node_src_components_shared
node_tests_workflow -.->|"stabilizes"| node_src_app_e2e
node_ops_workflow -.->|"guides"| node_src_actions

click node_src_app_root "https://github.com/coral0723/loglife/blob/main/src/app/layout.tsx"
click node_src_app_auth "https://github.com/coral0723/loglife/blob/main/src/app/(auth)/login/page.tsx"
click node_src_app_afterlogin "https://github.com/coral0723/loglife/blob/main/src/app/(afterLogin)/layout.tsx"
click node_src_app_modal "https://github.com/coral0723/loglife/blob/main/src/app/(afterLogin)/@modal/default.tsx"
click node_src_app_e2e "https://github.com/coral0723/loglife/blob/main/src/app/(e2e)/e2e-login/page.tsx"
click node_src_app_api_auth "https://github.com/coral0723/loglife/blob/main/src/app/api/auth/[...nextauth]/route.ts"
click node_src_app_api_data "https://github.com/coral0723/loglife/blob/main/src/app/api/bucketlists/[id]/route.ts"
click node_src_actions "https://github.com/coral0723/loglife/blob/main/src/actions/user/actions.ts"
click node_src_auth "https://github.com/coral0723/loglife/blob/main/src/auth.ts"
click node_src_lib_prisma "https://github.com/coral0723/loglife/blob/main/src/lib/prisma.ts"
click node_prisma_schema "https://github.com/coral0723/loglife/blob/main/prisma/schema.prisma"
click node_src_lib_domain "https://github.com/coral0723/loglife/blob/main/src/lib/bucketList/bucketStatus.ts"
click node_src_store "https://github.com/coral0723/loglife/blob/main/src/store/globeStore.ts"
click node_src_components_globe "https://github.com/coral0723/loglife/blob/main/src/components/globe/GlobeView.tsx"
click node_src_components_bucket "https://github.com/coral0723/loglife/blob/main/src/components/bucket/BucketDetailView.tsx"
click node_src_components_friends "https://github.com/coral0723/loglife/blob/main/src/components/friends/FriendsView.tsx"
click node_src_components_dashboard "https://github.com/coral0723/loglife/blob/main/src/components/dashboard/DashboardPanel.tsx"
click node_src_components_profile "https://github.com/coral0723/loglife/blob/main/src/components/profile/ProfileSettingsView.tsx"
click node_src_components_user "https://github.com/coral0723/loglife/blob/main/src/components/user/PublicProfileView.tsx"
click node_src_components_landing "https://github.com/coral0723/loglife/blob/main/src/components/landing/HeroContent.tsx"
click node_src_components_shared "https://github.com/coral0723/loglife/blob/main/src/components/ui/Button.tsx"
click node_tests_workflow "https://github.com/coral0723/loglife/blob/main/vitest.config.ts"
click node_ops_workflow "https://github.com/coral0723/loglife/blob/main/CLAUDE.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_app_root,node_src_app_auth,node_src_app_afterlogin,node_src_app_modal,node_src_app_e2e toneBlue
class node_src_store,node_src_components_globe,node_src_components_bucket,node_src_components_friends,node_src_components_dashboard,node_src_components_profile,node_src_components_user,node_src_components_landing,node_src_components_shared toneAmber
class node_src_lib_domain toneMint
class node_src_app_api_auth,node_src_app_api_data,node_src_actions,node_src_auth,node_src_lib_prisma,node_prisma_schema toneRose
class node_tests_workflow,node_ops_workflow toneIndigo
```

## Components

### Next.js App

Route groups, pages, API routes, and server actions in the main runtime.

- [App shell](https://github.com/coral0723/loglife/blob/main/src/app/layout.tsx): nextjs shell · Global app layout, error handling, PWA service worker, and route-wide providers. · `src/app/layout.tsx`
- [Auth routes](https://github.com/coral0723/loglife/blob/main/src/app/(auth)/login/page.tsx): route group · Public login flow separated from the authenticated app. · `src/app/(auth)/login/page.tsx`
- [App routes](https://github.com/coral0723/loglife/blob/main/src/app/(afterLogin)/layout.tsx): route group · Authenticated experience with main, friends, profile, onboarding, and modal overlays. · `src/app/(afterLogin)/layout.tsx`
- [Modal routes](https://github.com/coral0723/loglife/blob/main/src/app/(afterLogin)/@modal/default.tsx): parallel routes · Intercepting overlays for bucket details, friends, profile settings, and public profile dialogs. · `src/app/(afterLogin)/@modal/default.tsx`
- [E2E routes](https://github.com/coral0723/loglife/blob/main/src/app/(e2e)/e2e-login/page.tsx): test routes · Deterministic pages used to stabilize browser automation flows. · `src/app/(e2e)/e2e-login/page.tsx`

### UI Components

Reusable feature UIs composed by domain.

- [Client stores](https://github.com/coral0723/loglife/blob/main/src/store/globeStore.ts): state stores · Local interaction state for globe and bucket form flows. · `src/store/globeStore.ts`
- [Globe view](https://github.com/coral0723/loglife/blob/main/src/components/globe/GlobeView.tsx): visualization UI · Country globe, pin rendering, and slide-over country interactions. · `src/components/globe/GlobeView.tsx`
- [Bucket tools](https://github.com/coral0723/loglife/blob/main/src/components/bucket/BucketDetailView.tsx): feature UI · Bucket detail, creation, autocomplete, and matrix interactions. · `src/components/bucket/BucketDetailView.tsx`
- [Friends UI](https://github.com/coral0723/loglife/blob/main/src/components/friends/FriendsView.tsx): feature UI · Friend lists, requests, search, and social widgets. · `src/components/friends/FriendsView.tsx`
- [Dashboard UI](https://github.com/coral0723/loglife/blob/main/src/components/dashboard/DashboardPanel.tsx): feature UI · Achievement, counts, matrix, and upcoming deadline widgets. · `src/components/dashboard/DashboardPanel.tsx`
- [Profile UI](https://github.com/coral0723/loglife/blob/main/src/components/profile/ProfileSettingsView.tsx): feature UI · Nickname and avatar settings for the authenticated user. · `src/components/profile/ProfileSettingsView.tsx`
- [Public profile UI](https://github.com/coral0723/loglife/blob/main/src/components/user/PublicProfileView.tsx): feature UI · Shared user profile pages and profile sharing actions. · `src/components/user/PublicProfileView.tsx`
- [Landing UI](https://github.com/coral0723/loglife/blob/main/src/components/landing/HeroContent.tsx): marketing UI · Home page hero, feature mocks, and landing globe experience. · `src/components/landing/HeroContent.tsx`
- [Shared UI](https://github.com/coral0723/loglife/blob/main/src/components/ui/Button.tsx): base UI · Cross-cutting primitives such as nav, buttons, loading, offline, and image fallback. · `src/components/ui/Button.tsx`

### Domain Logic

Pure helpers and shared business rules.

- [Domain helpers](https://github.com/coral0723/loglife/blob/main/src/lib/bucketList/bucketStatus.ts): pure logic · Bucket status, visibility, achievements, friend relations, rate limiting, username rules, and geospatial helpers. · `src/lib/bucketList/bucketStatus.ts`

### Data Layer

Authentication, persistence, and external-service mediation.

- [Auth callback](https://github.com/coral0723/loglife/blob/main/src/app/api/auth/[...nextauth]/route.ts): api route · NextAuth callback endpoint for OAuth sign-in and session management. · `src/app/api/auth/[...nextauth]/route.ts`
- [Read APIs](https://github.com/coral0723/loglife/blob/main/src/app/api/bucketlists/[id]/route.ts): api routes · Domain read endpoints for bucket lists, dashboard metrics, friends, users, and place proxies. · `src/app/api/bucketlists/[id]/route.ts`
- [Server actions](https://github.com/coral0723/loglife/blob/main/src/actions/user/actions.ts): mutation layer · Domain mutations for bucket lists, friends, onboarding, and user profile updates. · `src/actions/user/actions.ts`
- [NextAuth setup](https://github.com/coral0723/loglife/blob/main/src/auth.ts): auth config · Auth.js/NextAuth v5 configuration and provider wiring. · `src/auth.ts`
- [Prisma access](https://github.com/coral0723/loglife/blob/main/src/lib/prisma.ts): db client · Shared Prisma client for Supabase Postgres persistence. · `src/lib/prisma.ts`
- [DB schema](https://github.com/coral0723/loglife/blob/main/prisma/schema.prisma): schema · Core tables for users, accounts, sessions, bucket lists, and friendships. · `prisma/schema.prisma`

### Workflow

Testing, Storybook, and repo-specific development tooling.

- [Tests](https://github.com/coral0723/loglife/blob/main/vitest.config.ts): quality stack · Vitest, Playwright, MSW, Storybook, and Chromatic coverage across the repo. · `vitest.config.ts`
- [Dev workflow](https://github.com/coral0723/loglife/blob/main/CLAUDE.md): tooling rules · Claude/agent instructions, memories, commands, and repo-specific development guidance. · `CLAUDE.md`

## Connections

- App shell → Auth routes: routes to · Public login is separated from the app shell.
- App shell → App routes: hosts · Authenticated route group runs under the shared shell.
- App routes → Modal routes: overlays · Main app can open route-addressable modals without leaving the screen.
- App routes → Globe view: renders · Main experience centers on the globe visualization.
- App routes → Dashboard UI: renders · Dashboard route composes analytics widgets.
- App routes → Friends UI: renders · Friends route composes social views and widgets.
- App routes → Profile UI: renders · Profile route exposes user settings.
- App routes → Bucket tools: renders · Bucket routes use detail and creation UI.
- Auth routes → NextAuth setup: uses · Login flow depends on NextAuth configuration.
- Auth callback → NextAuth setup: calls · Callback route delegates to auth setup.
- Read APIs → Prisma access: reads/writes · API routes access the shared database client.
- Server actions → Prisma access: mutates · Server actions persist domain changes through Prisma.
- Prisma access → DB schema: implements · Client is shaped by the Prisma schema.
- Read APIs → Domain helpers: computes · API endpoints rely on shared business rules and helpers.
- Server actions → Domain helpers: validates · Mutations use shared rules for bucket, friend, and profile state.
- Globe view → Client stores: uses · Globe UI is backed by local interaction stores.
- Bucket tools → Read APIs: fetches · Bucket UI consumes bucket and places endpoints.
- Friends UI → Read APIs: fetches · Friends UI consumes social and search endpoints.
- Dashboard UI → Read APIs: fetches · Dashboard widgets are driven by read APIs.
- Profile UI → Server actions: submits · Profile edits are written through server actions.
- Public profile UI → Read APIs: fetches · Public profile pages load user data through API routes.
- Landing UI → Globe view: reuses · Landing page shares globe presentation patterns.
- Tests → Shared UI: covers · Testing spans component, API, and end-to-end layers.
- Tests → E2E routes: stabilizes · Dedicated E2E routes support deterministic browser tests.
- Dev workflow → Server actions: guides · Repo rules shape mutation, review, and QA practices.