Skip to content
JournalTORIS / FIELD NOTES

← Blog Project notes

[Case Study] 21N E-Contract Platform: A Hospital-Model B2B2C Contract and Settlement System Designed Without a PG

How I designed contracts, points, and settlement for a hospital-model B2B2C platform around bank APIs and e-signature (Modusign) instead of a PG, covering regulatory limits and trade-offs.

10 min read Read the Korean original

Joohwan Yu · Founder, Full Stack Developer

Toris · Published

Contents

This post is a case-study write-up of a project I worked on as a full-stack developer while employed at 21N (21앤). It leaves out details that are sensitive for service contracts and security, and focuses on the working process and design decisions.

Q. How did you design a contract and settlement system in a regulatory environment where a PG could not be attached?

Without a PG, I used the KB Kookmin Bank API for account lookup and transfers, and integrated Modusign for e-signatures that need legal effect, tying contracts, points, and settlement into a single domain.

1. Background: Whose Problem Was It, and What Was It

21N was building a B2B2C service that connects hospitals and models (users). Hospitals recruit procedure models, and models sign contracts such as image-rights grants in exchange for receiving procedures. For this exchange to work, at least three things had to mesh inside one system.

  • Contracts with legal effect: Documents such as image-rights consent forms and payment pledges must be signed without paper, and be traceable in case of disputes or audits.
  • Flow of money: Settlement, including point payouts, coupons, and bank transfer requests and lookups, must never drift out of sync with contract state.
  • Three kinds of users: Models, hospital administrators, and the platform operator (21N) each need to see the same data through different screens and permissions.

Requirements by user group were as follows.

GroupPlatformKey features
User (model)React Native appE-signature and contract review, calendar, invite-code points, bank transfer requests and lookups, SNS linking, my page, notifications, social login (Naver, Kakao, Facebook, Google)
Hospital adminWebHospital and doctor info, contract management (image rights, payment pledges, etc.), model linking, coupons, settlement and refunds, Excel download
Platform admin (21N)WebDashboard, management of hospitals, applications, users, and coupons, point and transfer tracking, settings, metrics

I handled all three product lines full-stack: the React Native (Expo) app, the NestJS-based API, the Next.js admin web, and the Terraform-based infrastructure.

2. Constraints: Why “Just Attach a PG” Was Not an Option

The biggest constraint on this project was not technology but domain and regulation.

2.1 A Domain Where Medicine, Procedures, and Brokerage Overlap

Because the service was not plain e-commerce but touched medicine, procedures, and contracts, we had to go through, one by one with business and legal, how it overlapped with medical law, medical advertising, and brokerage rules. Legal interpretation is the domain of experts, so on the development side I focused on asking “which payment and settlement approaches are allowed” and writing the answers down.

2.2 PG Provider Policies

A PG can impose sign-up restrictions or hold reviews depending on industry, product, and settlement structure. In our domain, which mixed medical, beauty, and brokerage characteristics, “attach a PG first and see” was not always an open option.

2.3 A Thin Engineering Organization

21N started from an organization with a strong marketing background, and engineering headcount was limited. With one full-stack developer covering the app, API, admin, and infrastructure at once, self-built options with a heavy maintenance burden (for example, building e-signature in-house) had to be ruled out from the start.

2.4 The Design Conclusion the Constraints Produced

Law, business, and PG all had to be YES at once, and in our domain that was not easy. The conclusion was as follows.

  • Design the points, account, and contract flows without a PG.
  • Handle actual transfers and lookups through the KB Kookmin Bank API (account lookup and transfer).
  • Bring in e-signature, which needs legal effect, via Modusign integration.

The detailed review and persuasion process is written up separately in the operations retrospective.

Advertisement

3. Technical Design and Trade-offs

3.1 Stack Choices

AreaStackRationale / notes
AppReact Native, ExpoOne person covers iOS and Android at once. react-native-calendars, Noto Sans KR (@expo-google-fonts/noto-sans-kr, expo-font)
APINestJS, tRPC, DockerDomain APIs for e-signature, PDF, notifications, and so on. Types shared with the frontend through tRPC
AdminNext.jsPlatform admin and hospital admin
DBPostgreSQL (RDS Multi-AZ)Domains like contracts and points where consistency matters
FilesS3Contract PDFs, profile images, etc.
InfrastructureECS Fargate, ALB, Terraform, CloudWatch, WAFInfrastructure managed as code, mostly managed services that suit a thin team

3.2 Monorepo: Trading Convenience for Blast Radius

Because the app, API, and admin had to share the same domain types, I chose a monorepo.

  • apps/admin: admin web (Next.js)
  • apps/api: backend (NestJS)
  • apps/user-app: user app (Expo)
  • packages/*: DB, shared modules, and so on
  • docs/*: app and infrastructure docs

For local development, I standardized on a flow where the root docker-compose.yml brings up admin, api, and postgres together, and you copy .env.example to .env.development to start.

The trade-off was clear. Sharing types and constants is convenient, but a single mistake in a shared module ripples through all three apps at once. So the principle was “share as little as possible.” I put a structure with low deployment risk ahead of perfect DRY.

3.3 E-Signature: Why I Dropped Building It In-House and Chose Modusign

Building e-contracts and e-signatures in-house saves initial cost, but legal effect, audit trails, and dispute handling all become your own burden. I judged that a thin engineering team could not carry that risk, so after preparing Modusign’s corporate sign-up, verification, templates, API, and webhooks, I wove it into the backend, app, and admin. I kept three principles in the integration design.

  • Environment separation: API keys, webhook secrets, and template IDs are split across dev/stage/prod so production templates are never touched by accident
  • Idempotent webhooks: even if the same event arrives several times, the state transitions only once, aligned with the state machine in our DB
  • Agreeing on the source of truth for state: explicitly agree with the team on whether to keep intermediate signing states in our DB or trust only Modusign’s state

3.4 PDF Pipeline: Dropping the Synchronous API for a Queue

Contracts based on HTML templates had to be converted to PDF, with timestamps, hashes, and the like to keep them auditable. Puppeteer-based PDF generation is heavy and costs both time and money, so instead of wiring it as a synchronous API, I used queue-based asynchronous processing to separate API response from worker load.

Here is a simplified sequence of the signing flow.

sequenceDiagram
    participant User as User
    participant Backend as Server
    participant DB as Database
    participant PDF as PDF service
    participant Storage as S3

    User->>Backend: Request contract
    Backend->>DB: Create draft
    DB-->>Backend: Return contract ID
    Backend-->>User: Show contract screen

    User->>Backend: Submit signature
    Backend->>DB: Update signature status

    alt All parties have signed
        Backend->>PDF: Generate PDF
        PDF-->>Backend: Return PDF
        Backend->>Storage: Store
        Storage-->>Backend: Return URL
        Backend->>DB: Set status Completed
        Backend-->>User: Notify contract completed
    else Some signatures missing
        Backend-->>User: Notify pending signatures
    end

3.5 Points, Coupons, SNS: Fix the Rules Before the Code

  • Points: Write down payout rules first (for example, payout on invite-code entry, admin-assigned payouts), and make payouts idempotent so they happen exactly once
  • Coupons: A structure that allows issuance and usage tracking per hospital
  • SNS linking: YouTube, TikTok, and Naver Blog assume OAuth 2.0 integration, while Instagram was designed with a narrower scope because of platform policy

3.6 Treating Cost as a Design Variable

E-signature SaaS, cloud, and bank integrations all carry per-transaction or monthly fees. If you check cost after building every feature, the curve tends to diverge from expectations, so I built two things into the design from the start.

  • Staged rollout: turn on only the APIs and templates strictly needed for the MVP phase, and block the rest with flags and environment variables, making “open it later if needed” explicit in code and configuration
  • Async and retry policy: cut unnecessary external calls to manage billing and failure risk at the same time

The figures and the way I recorded trade-offs continue in §4 of the retrospective.

4. Coordinating with Stakeholders: The Real Difficulty of This Project

What was harder than the tech stack was aligning the languages of people and organizations.

“Why can’t we attach a PG” was not a question a developer could settle alone. We went through the keywords of medical law, medical advertising, and brokerage rules with business and legal one by one, and from the engineering side I asked about “the picture of permitted payment and settlement” and kept the answers in a document. Once “why a PG doesn’t work” was summarized on one page, I no longer had to repeat the same explanation to later team members or external partners.

4.2 With a Marketing-Centered Organization: The Gap in Schedule and Language

21N is an organization with many members used to campaigns, branding, and client communication. When “launch fast” met the marketing calendar, it took energy to explain the need for addressing tech debt, security, and testing, and I repeatedly had to unpack why “this is simple, right?” was not simple, since it was tangled up with data, permissions, and external integrations.

What narrowed this gap was explaining features in the language of customer journeys and conversion rather than “API endpoints,” and leaving cost, billing, and rollout decisions in tables and configuration to eliminate repeated explanation. As a result, my ability to explain business matters and to document grew fastest in this coordination work.

4.3 With External Partners: Applying Is Only the Start

Modusign requires corporate sign-up, verification, and template registration before you can use the real API. “We applied” is not the end; real integration work starts only after registration, and when a signing failure or timeout occurs, you need to be able to tell from logs where our bug ends and an external issue begins for communication with the partner to work.

5. Results and Operations

  • A structure emerged in which the three user groups of hospitals, models, and operators handle one contract, point, and settlement domain through their own channels (app, hospital admin, platform admin).
  • Even without a PG, the contract, signing, PDF storage, and point and transfer flow that met the service requirements ran end to end in code and infrastructure.
  • Environment-variable-based deployment (dev/stage/prod), Terraform-as-code, and a docker-compose local environment lowered deployment and onboarding cost even for a thin team.
  • Community, per-hospital transaction monitoring, and analytics and reporting were on the roadmap, and we were at the stage of weaving metrics and event design into the API and admin.

Summary of Key Decisions

DecisionChoiceReason (trade-off)
Payment structureNo PG; KB Kookmin Bank API (account lookup, transfer)Avoids PG review risk in a domain where medicine, beauty, and brokerage overlap. Gave up card payment convenience
E-signatureModusign integration (no in-house build)Delegates the burden of legal effect, audit trail, and dispute handling to SaaS. Accepted per-transaction billing and external dependency
Repo structureMonorepo with a minimal-sharing ruleGains the convenience of sharing types across app, API, and admin. Offsets the blast radius of shared-module mistakes by sharing minimally
PDF generationQueue-based async processingSeparates Puppeteer’s time and billing load from API responses. Needs status notifications instead of an immediate response
External billing controlFlag-based staged rolloutTurns on only the MVP scope to control the cost curve. Configuration management complexity increases

6. Reusable Lessons

  1. Draw the state machine and permission model before the screens. To connect one domain across app, API, admin, and infrastructure, fixing state transitions and permissions for things like contract state, points, and transfers first determines the speed of all later screen and API development.
  2. Design external integrations starting from failure scenarios. If you do not put failure, retry, and idempotency into e-contract, PDF, and bank integrations early, they cost far more in operation.
  3. Check regulatory constraints before features. If you build features and then fit regulation around them, costs explode. Leaving “why it can’t be done” on one page is what keeps the team fast.
  4. Share as little as possible in a monorepo. Fixing shared types, DB migrations, and environment variable naming as team rules lowers merge cost, while excessive sharing becomes deployment risk.
  5. Cost is a design variable, not a planning matter. External services with per-transaction billing must be designed together with flags, queues, and retry policies so the curve does not collapse.

Further reading: One Year as Full-Stack in a Marketing Organization: An Operations Retrospective


This post is a case study based on my experience during employment, and it does not include details that are sensitive for service contracts or security.

Advertisement