# kokiebisu/sumitsugi architecture

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

- Interactive diagram: https://gitdiagram.com/kokiebisu/sumitsugi
- Repository: https://github.com/kokiebisu/sumitsugi

## Overview

1. **Overall shape**
   - This is a Next.js 16 App Router application for a real-estate / lifestyle-transfer marketplace. The code is split into three main layers: route-level UI in `src/app`, shared domain logic in `src/lib`, and persistence/integration code in `src/db` plus external service adapters.

2. **User-facing application routes**
   - The app surface is organized by workflow: property browsing (`/properties`, `/listings`), listing creation/editing (`/listing`), inquiry and agreement flow (`/inquiry`, `/agreements`), payments (`/properties/[id]/payment`), account/dashboard/admin pages, and supporting content pages like privacy and terms.
   - These routes are the primary composition layer and mostly delegate business logic to server actions, API routes, and reusable components.

3. **Server-side interaction boundary**
   - Business-changing operations are concentrated in `src/app/actions` and `src/actions`, which act as the server action boundary for flows such as payments, refunds, escrow confirmation, Stripe Connect onboarding, messaging, and auth-related actions.
   - API routes under `src/app/api` handle external or programmatic entry points: auth, property CRUD, image upload, PDF generation, phone OTP, contract retrieval, estimate calculation, and Stripe webhooks.

4. **Persistence and schema**
   - PostgreSQL is the system of record, accessed through Drizzle ORM in `src/db`.
   - The schema models the core platform entities: users, sessions, properties, inquiries, payments, messages, handover confirmations, and email logs; migrations are versioned in `src/db/migrations`.
   - The data layer is intentionally explicit and is the source of truth for the architecture diagram’s core domain objects.

5. **Authentication and sessions**
   - Authentication is built around Better-auth, with route handling at `/api/auth/[...all]` and client/server helpers in `src/lib/auth*` and `src/contexts/auth-context.tsx`.
   - The auth subsystem supports email/password plus OAuth providers, and it feeds the user/session data used by dashboards, listing creation, inquiry flows, and admin pages.

6. **Property and listing domain**
   - Property/listing management is a major subsystem spanning CRUD APIs, listing pages, and specialized components for creation, status toggling, furniture metadata, pricing guidance, and previews/PDF views.
   - The app separates public browsing views from authenticated owner/editor flows, which is important for diagramming trust boundaries.

7. **Inquiry, agreement, and handover flow**
   - The inquiry pipeline connects browsing to transaction completion: a buyer submits an inquiry, then proceeds through agreement acceptance/signing and later handover confirmation.
   - Domain helpers in `src/lib/viewing-flow.ts`, `src/lib/handover-agreement.ts`, and validation modules enforce the workflow rules, while UI components render the step-specific forms and summaries.

8. **Payments and Stripe integration**
   - Payments are handled through Stripe Checkout and Stripe Connect, with fee calculation logic in `src/lib/stripe`, server-side payment actions, and a webhook handler at `/api/webhooks/stripe`.
   - The architecture treats Stripe as an external payment processor and escrow mechanism; payment state is persisted locally in the database and synchronized via webhook events.

9. **Files, media, and generated documents**
   - Image uploads use an S3-compatible storage abstraction: Cloudflare R2 in production and LocalStack in local development, exposed through the upload API.
   - PDF generation is a separate subsystem in `src/lib/pdf` with templates for agreements, consent forms, consultation docs, schedules, and marketing/explainer documents; these PDFs are surfaced through dedicated pages and API routes.

10. **Messaging and notifications**
   - Messaging is modeled as a domain feature with thread/list UI, message validation, and notification helpers.
   - Outbound notifications are handled through email templates and sending utilities in `src/lib/email`, and phone OTP flows live under `/api/phone`, implying a multi-channel notification boundary.

11. **Shared domain utilities**
   - `src/lib` contains the reusable business logic that doesn’t belong in a page or API route: estimate calculation, geocoding, station data, pricing guidance, cancellation penalties, review data/types, storage helpers, and validation schemas.
   - This layer is the main place where cross-cutting rules live, and it is what keeps the UI and API surfaces thin.

12. **Admin and operations**
   - There is a dedicated admin area and admin UI components for managing inquiries and seller listings.
   - Operationally, the repo is set up for a production app with Bun, Docker/devcontainer, PostgreSQL, LocalStack, Vercel deployment config, and GitHub Actions for CI, E2E, code review automation, branch cleanup, and docs/requirements audits.

13. **Testing strategy**
   - Unit tests with Vitest cover domain logic, schema, route handlers, and component behavior; Playwright E2E tests cover the key product journeys: auth, listing creation, property browsing, inquiry flow, dashboard, account, and payment/security scenarios.
   - For architecture purposes, the test suite mirrors the product boundaries very closely, which is a good signal for the repo’s modular decomposition.

14. **What to draw as the core runtime flow**
   - The main request path is: browser/UI → Next.js route or server action → shared lib/domain logic → Drizzle/PostgreSQL and/or external services (Stripe, auth provider, storage, email/SMS, PDF generation) → persisted state returned to UI.
   - The most important external boundaries are authentication, payment processing, object storage, and notification delivery, with the database as the center of state.

Main entry points: [`src/db/index.ts`](https://github.com/kokiebisu/sumitsugi/blob/main/src/db/index.ts) (Postgres), [`src/app/api`](https://github.com/kokiebisu/sumitsugi/tree/main/src/app/api) (API routes), [`src/app/actions`](https://github.com/kokiebisu/sumitsugi/tree/main/src/app/actions) (Server actions), [`src/lib/viewing-flow.ts`](https://github.com/kokiebisu/sumitsugi/blob/main/src/lib/viewing-flow.ts) (Domain rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_app["Next.js app"]
  node_app_home["Home<br/>marketing route<br/>[page.tsx]"]
  node_app_browse["Browse<br/>property routes<br/>[page.tsx]"]
  node_app_listing["Listing flow<br/>owner routes<br/>[page.tsx]"]
  node_app_inquiry["Inquiry flow<br/>transaction routes<br/>[page.tsx]"]
  node_app_payment["Payment pages<br/>payment routes<br/>[page.tsx]"]
  node_app_account["Account area<br/>user routes<br/>[page.tsx]"]
  node_app_admin["Admin area<br/>admin route<br/>[page.tsx]"]
  node_app_api["API routes<br/>server endpoints"]
  node_actions_boundary["Server actions<br/>mutation boundary"]
end

subgraph group_g_domain["Shared domain"]
  node_auth["Auth<br/>[auth.ts]"]
  node_domain_core["Domain rules<br/>business logic<br/>[viewing-flow.ts]"]
  node_domain_media["Docs & media<br/>generation<br/>[index.ts]"]
  node_domain_comm["Messaging & email<br/>notifications<br/>[messaging.ts]"]
end

subgraph group_g_data["Data layer"]
  node_db[("Postgres<br/>drizzle database<br/>[index.ts]")]
  node_schema["Schema<br/>entities<br/>[index.ts]"]
  node_migrations["Migrations<br/>versioned sql"]
end

subgraph group_g_externals["External services"]
  node_payments["Stripe<br/>payment integration<br/>[server.ts]"]
  node_storage[("Object storage<br/>r2/localstack<br/>[storage.ts]")]
end

subgraph group_g_ops["Ops and QA"]
  node_ci_tests["Tests<br/>vitest/playwright"]
  node_automation["Automation<br/>scripts/ci<br/>[autonomous-dev.ts]"]
end

node_app_home -->|"routes to"| node_app_browse
node_app_browse -->|"starts inquiry"| node_app_inquiry
node_app_listing -->|"mutates via"| node_actions_boundary
node_app_inquiry -->|"mutates via"| node_actions_boundary
node_app_payment -->|"mutates via"| node_actions_boundary
node_app_account -->|"uses"| node_auth
node_app_admin -->|"reads"| node_db
node_app_api -->|"authenticates"| node_auth
node_app_api -->|"validates"| node_domain_core
node_app_api -->|"generates"| node_domain_media
node_app_api -->|"webhooks"| node_payments
node_actions_boundary -->|"orchestrates"| node_domain_core
node_actions_boundary -->|"writes"| node_db
node_domain_core -->|"reads/writes"| node_db
node_domain_comm -->|"logs"| node_db
node_domain_media -->|"uploads"| node_storage
node_payments -->|"syncs state"| node_db
node_payments -->|"calculates fees"| node_domain_core
node_auth -->|"sessions"| node_db
node_schema -->|"defines"| node_db
node_migrations -->|"evolves"| node_schema
node_ci_tests -->|"covers"| node_app_api
node_ci_tests -->|"covers"| node_domain_core
node_ci_tests -->|"covers"| node_app_listing
node_automation -->|"runs"| node_ci_tests
node_automation -->|"migrates"| node_db

click node_app_home "https://github.com/kokiebisu/sumitsugi/blob/main/src/app/page.tsx"
click node_app_browse "https://github.com/kokiebisu/sumitsugi/blob/main/src/app/properties/page.tsx"
click node_app_listing "https://github.com/kokiebisu/sumitsugi/blob/main/src/app/listing/page.tsx"
click node_app_inquiry "https://github.com/kokiebisu/sumitsugi/blob/main/src/app/inquiry/[id]/agreement/page.tsx"
click node_app_payment "https://github.com/kokiebisu/sumitsugi/blob/main/src/app/properties/[id]/payment/page.tsx"
click node_app_account "https://github.com/kokiebisu/sumitsugi/blob/main/src/app/account/page.tsx"
click node_app_admin "https://github.com/kokiebisu/sumitsugi/blob/main/src/app/admin/page.tsx"
click node_app_api "https://github.com/kokiebisu/sumitsugi/tree/main/src/app/api"
click node_actions_boundary "https://github.com/kokiebisu/sumitsugi/tree/main/src/app/actions"
click node_auth "https://github.com/kokiebisu/sumitsugi/blob/main/src/lib/auth.ts"
click node_domain_core "https://github.com/kokiebisu/sumitsugi/blob/main/src/lib/viewing-flow.ts"
click node_domain_media "https://github.com/kokiebisu/sumitsugi/blob/main/src/lib/pdf/index.ts"
click node_domain_comm "https://github.com/kokiebisu/sumitsugi/blob/main/src/lib/messaging.ts"
click node_payments "https://github.com/kokiebisu/sumitsugi/blob/main/src/lib/stripe/server.ts"
click node_storage "https://github.com/kokiebisu/sumitsugi/blob/main/src/lib/storage.ts"
click node_db "https://github.com/kokiebisu/sumitsugi/blob/main/src/db/index.ts"
click node_schema "https://github.com/kokiebisu/sumitsugi/blob/main/src/db/schema/index.ts"
click node_migrations "https://github.com/kokiebisu/sumitsugi/blob/main/src/db/migrations/0000_yielding_patch.sql"
click node_ci_tests "https://github.com/kokiebisu/sumitsugi/tree/main/tests/e2e"
click node_automation "https://github.com/kokiebisu/sumitsugi/blob/main/scripts/autonomous-dev.ts"

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_app_home,node_app_browse,node_app_listing,node_app_inquiry,node_app_payment,node_app_account,node_app_admin,node_app_api,node_actions_boundary toneBlue
class node_auth,node_domain_core,node_domain_media,node_domain_comm toneAmber
class node_db,node_schema,node_migrations toneMint
class node_payments,node_storage toneRose
class node_ci_tests,node_automation toneIndigo
```

## Components

### Next.js app

Route-level UI and server entrypoints.

- [Home](https://github.com/kokiebisu/sumitsugi/blob/main/src/app/page.tsx): marketing route · Public landing and supporting content pages. · `src/app/page.tsx`
- [Browse](https://github.com/kokiebisu/sumitsugi/blob/main/src/app/properties/page.tsx): property routes · Property and listing browsing surfaces, including detail and inquiry entry. · `src/app/properties/page.tsx`
- [Listing flow](https://github.com/kokiebisu/sumitsugi/blob/main/src/app/listing/page.tsx): owner routes · Create, edit, preview, PDF, and onboarding pages for seller listings. · `src/app/listing/page.tsx`
- [Inquiry flow](https://github.com/kokiebisu/sumitsugi/blob/main/src/app/inquiry/[id]/agreement/page.tsx): transaction routes · Inquiry, agreement acceptance/signing, and viewing completion pages. · `src/app/inquiry/[id]/agreement/page.tsx`
- [Payment pages](https://github.com/kokiebisu/sumitsugi/blob/main/src/app/properties/[id]/payment/page.tsx): payment routes · Property payment and handover-related UI surfaces. · `src/app/properties/[id]/payment/page.tsx`
- [Account area](https://github.com/kokiebisu/sumitsugi/blob/main/src/app/account/page.tsx): user routes · Account, edit, Stripe setup, and dashboard pages. · `src/app/account/page.tsx`
- [Admin area](https://github.com/kokiebisu/sumitsugi/blob/main/src/app/admin/page.tsx): admin route · Operational views for inquiries and seller listings. · `src/app/admin/page.tsx`
- [API routes](https://github.com/kokiebisu/sumitsugi/tree/main/src/app/api): server endpoints · Programmatic and external entrypoints for auth, CRUD, uploads, docs, and webhooks. · `src/app/api`
- [Server actions](https://github.com/kokiebisu/sumitsugi/tree/main/src/app/actions): mutation boundary · Business-changing operations for inquiry, payment, refund, escrow, and Stripe Connect flows. · `src/app/actions`

### Shared domain

Reusable business logic, validation, and integrations.

- [Auth](https://github.com/kokiebisu/sumitsugi/blob/main/src/lib/auth.ts): better-auth · Authentication helpers, context, and route handling for sessions and login providers. · `src/lib/auth.ts`
- [Domain rules](https://github.com/kokiebisu/sumitsugi/blob/main/src/lib/viewing-flow.ts): business logic · Shared rules for viewing flow, handover agreements, messaging, pricing, estimates, and validation. · `src/lib/viewing-flow.ts`
- [Docs & media](https://github.com/kokiebisu/sumitsugi/blob/main/src/lib/pdf/index.ts): generation · PDF generation, templates, upload/storage helpers, and image/document delivery. · `src/lib/pdf/index.ts`
- [Messaging & email](https://github.com/kokiebisu/sumitsugi/blob/main/src/lib/messaging.ts): notifications · Thread/message logic plus email templates and sending utilities. · `src/lib/messaging.ts`

### Data layer

Drizzle schema, migrations, and database access.

- [Postgres](https://github.com/kokiebisu/sumitsugi/blob/main/src/db/index.ts): drizzle database · System of record for users, sessions, properties, inquiries, payments, messages, handovers, and email logs. · `src/db/index.ts`
- [Schema](https://github.com/kokiebisu/sumitsugi/blob/main/src/db/schema/index.ts): entities · Core table definitions and shared schema modules. · `src/db/schema/index.ts`
- [Migrations](https://github.com/kokiebisu/sumitsugi/blob/main/src/db/migrations/0000_yielding_patch.sql): versioned sql · Database migration history for schema evolution. · `src/db/migrations/0000_yielding_patch.sql`

### External services

Third-party or infrastructure boundaries.

- [Stripe](https://github.com/kokiebisu/sumitsugi/blob/main/src/lib/stripe/server.ts): payment integration · Stripe client/server config, fee calculations, and webhook handling. · `src/lib/stripe/server.ts`
- [Object storage](https://github.com/kokiebisu/sumitsugi/blob/main/src/lib/storage.ts): r2/localstack · S3-compatible storage abstraction used for uploads and media. · `src/lib/storage.ts`

### Ops and QA

Automation, deployment, and test coverage.

- [Tests](https://github.com/kokiebisu/sumitsugi/tree/main/tests/e2e): vitest/playwright · Unit, API, component, and end-to-end coverage aligned to product workflows. · `tests/e2e`
- [Automation](https://github.com/kokiebisu/sumitsugi/blob/main/scripts/autonomous-dev.ts): scripts/ci · Build, deploy, knowledge-update, and local ops scripts plus GitHub Actions. · `scripts/autonomous-dev.ts`

## Connections

- Home → Browse: routes to · Public browsing entry points lead into property discovery.
- Browse → Inquiry flow: starts inquiry · Buyer browsing transitions into the inquiry workflow.
- Listing flow → Server actions: mutates via · Listing creation and edits are committed through server actions.
- Inquiry flow → Server actions: mutates via · Inquiry, agreement, and handover steps use server actions.
- Payment pages → Server actions: mutates via · Payment and escrow steps are executed through server actions.
- Account area → Auth: uses · Account and dashboard surfaces depend on authenticated session data.
- Admin area → Postgres: reads · Admin views are backed by platform records.
- API routes → Auth: authenticates · Auth route handling is a primary API boundary.
- API routes → Domain rules: validates · API handlers delegate rules to shared domain logic.
- API routes → Docs & media: generates · PDF and upload endpoints rely on document/media helpers.
- API routes → Stripe: webhooks · Stripe webhook processing is exposed through API routes.
- Server actions → Domain rules: orchestrates · Server actions coordinate shared workflow rules.
- Server actions → Postgres: writes · Mutations persist platform state in Postgres.
- Domain rules → Postgres: reads/writes · Core business logic is grounded in persisted entities.
- Messaging & email → Postgres: logs · Message and email activity is stored alongside domain records.
- Docs & media → Object storage: uploads · Generated and user-provided files are stored through the object store abstraction.
- Stripe → Postgres: syncs state · Payment status is persisted locally and reconciled with Stripe events.
- Stripe → Domain rules: calculates fees · Fee and escrow calculations are shared with application logic.
- Auth → Postgres: sessions · Users and sessions are sourced from the database.
- Schema → Postgres: defines · Schema modules define the database model used by the app.
- Migrations → Schema: evolves · Migration history tracks schema changes over time.
- Tests → API routes: covers · API routes are covered by unit and integration tests.
- Tests → Domain rules: covers · Domain helpers are tested directly.
- Tests → Listing flow: covers · E2E flows exercise key product journeys.
- Automation → Tests: runs · CI and scripts execute the test suite and operational workflows.
- Automation → Postgres: migrates · Operational scripts include database migration workflows.
