KStudeo Photography Booking and Client Portal System
KStudeo is a photography booking and client portal system that allows customers to book photography sessions, select services and packages, provide session details, and pay securely online using Stripe.
The platform extends the existing public marketing website with a secure customer portal and a photographer administration dashboard. After successful payment, customers receive an email with a secure link to create their account and access the portal. The photographer reviews and approves bookings, uploads photographs to customers’ private galleries, and approves gallery access. Customers receive email notifications when their galleries become available, allowing them to view, download, and rate their photographs. The photographer receives notifications when customers submit ratings.
KStudeo also includes a referral and rewards system. Customers receive unique referral codes to invite new clients and earn percentage-based rewards on qualifying bookings. Earned rewards are applied as discounts on future photography bookings, subject to the configured reward rules.
The system uses Next.js, TypeScript, and Tailwind CSS for the frontend, Node.js and Express for the REST API, and PostgreSQL hosted on ScalaHosting for data storage. A separate background worker handles asynchronous tasks such as email notifications and image processing. Stripe processes payments in US dollars (USD). Database queries go through the generated Prisma Client, which connects only with DATABASE_URL. All monetary amounts are stored as integer cents, with currency = 'USD'.
The application follows a modular architecture that separates the frontend, API, background worker, and database while keeping the business logic organized and maintainable. Docusaurus provides the technical documentation for the system architecture, database schema, API endpoints, security controls, development procedures, testing, and deployment.
Add the booking workflow stepsClarify customer and photographer permissions
Stripe process payments in US dollars. Every order amount, payment amount, and reward value is stored as an integer number of cents with currency = 'USD'.
Business rules
Booking approval is required. A verified payment moves the booking to pending approval. The photographer makes the final decision. A browser redirect from Stripe does not confirm payment and does not confirm the booking.
Gallery access requires approval. The photographer approves gallery access before the customer views or downloads photographs. A published gallery remains private until that approval. The API enforces the rule on every view and download.
Referral rewards are percentage discounts. A qualifying order creates a reward from the policy active at that time. The reward is credited in USD cents and can be spent as a discount on an eligible future booking. Rewards are not cash payouts.
Readers
| Reader | Start here |
|---|---|
| Product and stakeholders | Project overview and user stories |
| Engineers implementing the system | Database schema, Prisma and migrations, and the API overview |
| Security review | Authentication and the threat model |
| Operations | Infrastructure and recovery |
System in one page
Visitors browse the existing KStudeo marketing pages. Customers book a package, pay in USD, and receive an account setup link when the payment is new. Existing customers keep the account they already have. The photographer approves or rejects the paid booking. A rejection starts the refund process.
After the session, the photographer uploads originals to private storage, publishes the gallery, and then grants access. The customer can view, download, and rate photographs only after both publication and access approval. Ratings notify the photographer.
A referred customer's qualifying order can earn the referrer a percentage reward. The referrer spends that balance as a discount on a later booking. Credits, redemptions, and reversals are immutable ledger entries.
Architecture decisions
- Next.js and TypeScript handle the landing page, booking, checkout, customer portal, and photographer dashboard.
- Express owns business rules, authentication, payment processing, gallery permissions, and rewards.
- PostgreSQL stores business records and access-control decisions.
- The generated Prisma Client is the only database client. It connects with
DATABASE_URL. - Private object storage holds image files. The database stores object keys and metadata.
- A background worker processes email, image thumbnails, and retryable jobs.
- This Docusaurus site publishes the system documentation.
- OpenAPI describes the REST API. Mermaid diagrams document workflows, data relationships, and C4 architecture views.
- The frontend, Express API, worker, and PostgreSQL database remain logically separate. Hosting placement is confirmed against ScalaHosting before each service is assigned a machine.
What this edition specifies
The pages in this site are the design baseline for implementation:
- Requirements, user stories, and acceptance criteria.
- C4 architecture and workflow diagrams.
- The PostgreSQL schema and the Prisma schema and migration plan, including gallery approval history, payment-event deduplication, and the immutable reward ledger.
- The OpenAPI 3.1 specification.
- The authentication design and threat model.
- The test plan and deployment, backup, and recovery instructions.
- The implementation roadmap.
Applied database migrations, application code, and automated tests begin from this baseline. They are later implementation phases, not artifacts already running in the marketing site.