How kokiebisu/sumitsugi works
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: index.ts Postgres · api API routes · actions Server actions · viewing-flow.ts Domain rules
Components 20
Next.js app
Route-level UI and server entrypoints.
- Home · Public landing and supporting content pages.
src/app/page.tsx - Browse · Property and listing browsing surfaces, including detail and inquiry entry.
src/app/properties/page.tsx - Listing flow · Create, edit, preview, PDF, and onboarding pages for seller listings.
src/app/listing/page.tsx - Inquiry flow · Inquiry, agreement acceptance/signing, and viewing completion pages.
src/app/inquiry/[id]/agreement/page.tsx - Payment pages · Property payment and handover-related UI surfaces.
src/app/properties/[id]/payment/page.tsx - Account area · Account, edit, Stripe setup, and dashboard pages.
src/app/account/page.tsx - Admin area · Operational views for inquiries and seller listings.
src/app/admin/page.tsx - API routes · Programmatic and external entrypoints for auth, CRUD, uploads, docs, and webhooks.
src/app/api - Server actions · Business-changing operations for inquiry, payment, refund, escrow, and Stripe Connect flows.
src/app/actions
Shared domain
Reusable business logic, validation, and integrations.
- Auth · Authentication helpers, context, and route handling for sessions and login providers.
src/lib/auth.ts - Domain rules · Shared rules for viewing flow, handover agreements, messaging, pricing, estimates, and validation.
src/lib/viewing-flow.ts - Docs & media · PDF generation, templates, upload/storage helpers, and image/document delivery.
src/lib/pdf/index.ts - Messaging & email · Thread/message logic plus email templates and sending utilities.
src/lib/messaging.ts
Data layer
Drizzle schema, migrations, and database access.
- Postgres · System of record for users, sessions, properties, inquiries, payments, messages, handovers, and email logs.
src/db/index.ts - Schema · Core table definitions and shared schema modules.
src/db/schema/index.ts - Migrations · Database migration history for schema evolution.
src/db/migrations/0000_yielding_patch.sql
External services
Third-party or infrastructure boundaries.
- Stripe · Stripe client/server config, fee calculations, and webhook handling.
src/lib/stripe/server.ts - Object storage · S3-compatible storage abstraction used for uploads and media.
src/lib/storage.ts
Ops and QA
Automation, deployment, and test coverage.
- Tests · Unit, API, component, and end-to-end coverage aligned to product workflows.
tests/e2e - Automation · Build, deploy, knowledge-update, and local ops scripts plus GitHub Actions.
scripts/autonomous-dev.ts
Connections 26
- 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.