Thithi-Yoga-Karanam-led matrimony site: architecture and roadmap

We are building a matrimony site where the Guru's chart-matching method ranks and explains every match, running entirely on Cloudflare with all matching logic on the server.

The reference site (mayyam.in) supplies the general shape: register, build a profile, search with filters, view a profile, express interest. Our difference is that birth data is a required input, charts are computed by our backend, and search results are ordered by compatibility for the logged-in member.

Ground rules for the team

• Own members only. We reuse the common profile field list and the general flow. We do not copy the reference site's member data, photos, text, branding or code.
• Server decides everything. Chart calculation, match scoring, tier gating and field redaction all happen in Workers. The browser only renders what it is given.
• Privacy by default. Guests see a minimal card. Contact details, exact birth data and family details are released only by tier and by mutual interest.
• One URL per state. Search filters live in the query string and every profile has a server-rendered page, so pages are shareable and indexable where we allow it.

Everything runs on Cloudflare: one front-end Worker for pages, one API Worker for data and logic, D1 for records, R2 for photos. The front end never talks to D1 or R2 directly.

On D1. It is a good starting point: cheap, zero-ops, and fine for tens of thousands of profiles. Its limits are a 10 GB cap per database, a single write region, and no full-text or geo search. Keep all SQL behind a repository layer so a later move to Postgres (through Hyperdrive) touches one module. Do not put queries in route handlers.

On the chart library. Swiss Ephemeris is the standard for planetary positions and compiles to WebAssembly, which Workers can run. It is dual-licensed (AGPL or a paid licence), so decide on the licence before using it in a closed-source product. If the WASM bundle proves too heavy for a Worker, the fallback is a small container service behind the Match Worker; nothing else in the design changes.

The profile is split across tables by sensitivity, so a query for a guest card cannot accidentally select contact or birth data.

Fields the team expects to add or remove later go in a JSON extras column rather than new migrations.

Indexes that search depends on: profiles(status, gender, dob), profile_religion(caste, star), profile_location(state, district), match_scores(profile_a, score).

Profile status values: REGISTERED (account only), PENDING (submitted, awaiting approval), ACTIVE, HOLD, HIDDEN, CLOSED. Only ACTIVE profiles ever appear in search or on public URLs.

Registration is a short account step followed by a guided profile wizard, and a profile goes live only after staff approval.

Phone OTP is the primary identity check because most members will register from a phone, often a parent on behalf of the bride or groom.

Registration rules

• Turnstile on the sign-up form; rate limit OTP sends to 3 per phone per hour and 5 verify attempts per code.
• Members must be of legal marriage age (21 for men, 18 for women in India today); check at sign-up from the date of birth.
• "Profile created for" (self, son, daughter, sibling, relative) is recorded, plus explicit consent that the person described agrees to the listing.
• Handle is generated from the display name plus a short random suffix, not a running number, so handles cannot be enumerated.
• Birth time has an accuracy field (exact, approximate, unknown). The matching engine needs to know how to treat the last two.

Login

• Phone or email plus password, or phone plus OTP. Google sign-in is optional and can wait for a later phase.
• Passwords hashed with Argon2id or PBKDF2 through the Web Crypto API (bcrypt is slow on Workers).
• On success the API Worker sets an HttpOnly, Secure, SameSite=Lax session cookie holding a random token. Only a hash of the token is stored. Sessions last 30 days and slide on use.
• Every API request resolves the session to {user_id, role, plan} in middleware. Handlers receive that context and never read the cookie themselves.
• Lock the account for 15 minutes after 10 failed attempts. Password reset is by OTP to the verified phone.

One serializer in the API Worker decides which fields a viewer receives, and every endpoint that returns a profile goes through it.

The front end shows a "register to view" or "upgrade to view" prompt wherever a section arrives empty.

Profile page. GET /p/{handle} is server-rendered by the Web Worker, which calls GET /api/v1/profiles/{handle} with the viewer's session. Sections mirror the data model: about, basic details, religion and horoscope, professional, location, family, lifestyle, partner preferences, contact. Non-active profiles return 404 to everyone except the owner and staff.

Actions on a profile

Editing. Members edit their own profile section by section through PATCH /api/v1/me/profile/{section}. Changes to name, about text and photos go back through approval; other fields apply immediately. Any change to birth data queues a chart recompute.

Search is one endpoint where every filter is optional, and the page URL always mirrors the filters in use.

A search with no values and a search with ten values run the same code path; the only difference is how many conditions are added to the query.

GET /api/v1/search?gender=F&age_min=24&age_max=30&caste=12,15&star=4&state=TN&sort=match&page=2

With no values

The server applies defaults rather than returning everything.

With values

Each parameter that is present adds one condition. Absent or empty parameters add nothing.

Fixed conditions on every search, which no parameter can override: status is ACTIVE, the viewer's own profile and blocked profiles are excluded, and results pass through the visibility serializer.

Response

{
  "total": 1240,
  "page": 2,
  "page_size": 20,
  "applied": { "gender": "F", "age_min": 24, "age_max": 30, "caste": [12, 15] },
  "results": [ { "handle": "...", "first_name": "...", "age": 27, "height_cm": 160,
                 "city": "...", "education": "...", "occupation": "...",
                 "photo": "https://.../blurred.webp", "score": 82 } ]
}

applied echoes the filters the server actually used, including defaults, so the page can show them as removable chips. score is present only for logged-in members.

Implementation notes

• Build the SQL with a query builder and bound parameters. Whitelist every parameter and every sort value; reject unknown ones with a 400.
• Parameters are plain ids and numbers. Never accept serialized objects from the client.
• One request returns one full page. Cache the total count for a filter set in KV for a minute so paging does not recount.
• Filter changes update the URL with history.replaceState and re-fetch after a 300 ms pause, so the back button and shared links work.
• Sorting by match joins match_scores for the logged-in member. Profiles without a score yet sort last and are queued for scoring.
• Dropdown lists come from GET /api/v1/lookups/{type}, cached in KV and at the edge. District depends on state, sub-caste on caste.
• Saved searches: POST /api/v1/me/searches stores the filter object under a name.
• Rate limit guests to about 30 searches per 10 minutes per IP.

The Guru's method lives in one server-side module with a fixed interface, so the rest of the site can be built before the rules are final.

Nothing about the rules, weights or intermediate values is shipped to the browser; clients receive a score and an explanation.

Module interface

Design rules

• Rules are data where possible: a versioned rules table or JSON (rule id, weight, condition) that the Guru's team can adjust through the admin screen without a code deploy. Rules that need real logic stay in code.
• Every chart and score stores the method_version that produced it. When the rules change, bump the version and let the queue recompute in the background; old scores stay visible until replaced.
• Candidate selection keeps the work bounded. For a new profile, score only against active profiles of the other gender within the preference age band, typically a few thousand pairs, processed in batches of 100 per queue message.
• Scores are symmetric unless the method says otherwise; store one row per pair with the lower id first.
• Approximate or unknown birth time: the engine must state which rules it skipped, and the explanation must say the result is partial.
• Include a manual override: the Guru or staff can pin a verdict and note on a pair, which takes precedence over the computed one.
• Build a test suite from 20 to 30 pairs the Guru has already judged by hand. The engine is not released until it reproduces his verdicts on them.

Endpoints

Staff tools are a separate app on their own hostname (for example admin.), protected by Cloudflare Access, so no staff screens or staff-only fields are ever bundled into the member site.

• Approval queue. New and edited profiles and photos wait here. Staff approve, reject with a reason, or put a profile on hold.
• Member support. Look up a member, view payment history, reset access, create a profile on behalf of a walk-in customer.
• Reports. Review reported profiles; block or close accounts.
• Method console. Edit rule weights, publish a new method version, trigger recompute, pin manual verdicts.
• Lookups. Maintain castes, sub-castes, education and location lists in English and Tamil.
• Audit log. Every staff action that reads contact details or changes a profile is recorded.

Payments. Razorpay Checkout on the plan page. The API Worker creates the order, and a signed webhook (POST /api/v1/webhooks/razorpay) is the only thing that activates a plan. Plans define duration, contact-view quota and daily interest cap. Offline payments at the Guru's office are entered by staff and flow through the same plan activation code.

A matrimony site holds birth details, caste, income, family and phone numbers, so the API must be safe even if someone calls it directly without the website.

These are the requirements to review each endpoint against.

• Redact on the server. Responses contain only what the viewer's tier allows. No internal fields (staff names, follow-up notes, IP addresses, internal ids, non-active statuses) in any member-facing response.
• Photos. Originals live in a private R2 bucket. Clients get short-lived signed URLs to the variant their tier allows. Blurring is done at upload, not with CSS.
• Input. Validate every request body and query with a schema (Zod). Bound parameters only. Plain ids in, never serialized objects.
• Abuse. Turnstile on public forms; WAF rate limits on auth, OTP, search and profile views; daily caps on interests and contact views; random handles so profiles cannot be walked in sequence.
• Sessions. HttpOnly cookies, CSRF token or same-site checks on state-changing requests, staff behind Cloudflare Access with 2FA.
• Secrets. Worker secrets for API keys; separate D1 databases and R2 buckets for dev, staging and production; no production data in lower environments.
• India's DPDP Act. Clear consent notice at sign-up, purpose limitation, a way to download and delete one's data, a named grievance contact, and breach notification duties. Get this reviewed by a lawyer before launch.
• Deletion. Closing an account removes photos and contact data and anonymises the rest after a fixed retention period.
• Backups. D1 Time Travel covers 30 days; add a weekly export to R2.

Six phases take the site from empty repository to public launch in about 18 weeks for a team of two or three developers.

The durations are estimates to be revised once the team and the Guru's rule set are known.

Phases 2 and 3 overlap on purpose: search does not depend on the engine, and the engine work can start as soon as the Guru's rules are written down.

Team

• One full-stack developer on the Web Worker and UI.
• One backend developer on the API, D1 and queues.
• One person pairing with the Guru to turn his method into written rules and test pairs; this is the critical path for phase 3.
• Part-time design and QA; staff from the Guru's office to run the approval queue from phase 1 testing onward.

These need answers before the affected phase starts; the first three block the matching engine design.

• What does the Guru's method take as input and produce: star-based porutham with his own weights, full chart analysis with dashas and planetary positions, or a manual review per pair?
• Which ayanamsa and chart style does he use (Lahiri, KP, other; South Indian chart layout)?
• How should profiles with approximate or unknown birth time be handled: partial score, excluded from match sort, or referred to him?
• Which communities and languages at launch: one community in Tamil and English, or several?
• Tiers and pricing: what does a free member see, what do paid plans unlock, and are there offline payments at his office?
• Does he have existing clients to invite at launch, and have they consented to being listed online?
• Swiss Ephemeris licence: AGPL (open-source our engine) or buy the commercial licence?
• Front-end framework: Next.js on Workers or Astro? Decide in phase 0 based on the team's experience.
• Who on his staff will run approvals and support, and in what hours?
• Domain name and brand, and whether the site sits alongside the existing Cloudflare sites or in a separate account.