PINECOCO · DEVELOPER PORTAL

Travel app được xây
bằng cả trái tim.

PineCoco là PWA giúp người Việt lên kế hoạch, chia tiền và lưu ký ức chuyến đi — xây trên Next.js 15, thiết kế glass-morphism, AI từ Google Gemini.

72+
Screens
76+
API Routes
3
AI Integrations
PWA
Offline-ready
i18n
Tiếng Việt first

Giao diện thực tế

Mobile-first PWA · max-width 448px · glass-morphism trên mọi màn hình

Trang chủ
Trang chủ
Quick actions, trip overview
AI Lên kế hoạch
AI Lên kế hoạch
Gemini-powered itinerary
Khám phá
Khám phá
Community trip templates
Thanh toán
Thanh toán
Payment methods & wallet
Cài đặt
Cài đặt
Profile & preferences
Hồ sơ
Hồ sơ
Avatar & account info

Design System

Hệ thống thiết kế nhất quán từ token màu sắc, typography, spacing đến component — lấy cảm hứng từ iOS glass và editorial heavy-black.

Brand Colors

Lime là màu duy nhất được dùng làm điểm nhấn (accent). Không dùng nhiều màu cùng lúc.

Lime
#c9f158--color-lime
Primary accent — CTA buttons, badges, highlights
Dark
#202020--color-dark
Headlines, text on light, dark surfaces
Surface
#f2f3f5--color-surface
Page background, input fills, muted areas
Card
#ffffff--color-card
Elevated surfaces, modals, sheets
Muted
#6b7280--color-muted
Secondary text, placeholders, captions
Dark bg
#171717--color-dark-bg
App dark mode base (hsl 0 0% 9%)

Glass & Dark Mode Tokens

CSS custom properties dùng trong toàn bộ lớp glass của app.

--glass-fillrgba(22,22,22,0.80)Card backgrounds in dark app shell
--glass-headerrgba(20,20,20,0.92)Nav bar / sticky header blur layer
--glass-borderrgba(255,255,255,0.08)Thin ring on glass surfaces
--blur-cardblur(24px)backdrop-filter on enhanced-glass-card
--blur-headerblur(32px)backdrop-filter on glass-header
--shadow-card0 8px 32px rgba(0,0,0,0.24)Floating glass cards
--shadow-sheet0 -4px 40px rgba(0,0,0,0.36)Bottom sheets & drawers

Spacing Scale (4px base)

Tất cả spacing đều là bội số của 4px. Padding container: 24px mobile, 40px tablet, 80px desktop.

4
8
12
16
20
24
32
40
48
64
80
96

Typography

Manrope cho app (Variable, 400–900) · Space Grotesk cho developer portal (400–700)

Display Mega · 900Hero heading only
PineCoco
Display Large · 800Section hero
Hành trình của bạn
H1 · 28px / 700Page titles
Lên kế hoạch chuyến đi
H2 · 22px / 700Section titles
Chia sẻ kỷ niệm
Body · 16px / 400lineHeight 1.6
Ứng dụng du lịch dành cho người Việt, xây với tình yêu.
Caption · 12px / 700letterSpacing 0.1em
UPPERCASE · TRACKING WIDEST · LABELS

Components

Buttons
borderRadius: 14px · fontWeight: 700 · Space Grotesk
Glass Card (App surface)
rgba(22,22,22,0.80) + blur(24px) + ring
Total Balance
₫ 4,250,000
Pay
Split
History
In-house SVG Icons
24 × 24 · stroke-based · public/svg/
home
home
calendar
calendar
wallet
wallet
scan
scan
explorer
explorer
add
add
archive
archive
chart
chart
join
join
profile
profile
airplanes
airplanes
flask
flask
Border Radius Scale
6px inputs → 48px sheets → pill nav bar
6
8
12
16
24
32
40
48
pill
Animation Tokens (Framer Motion)
Spring physics — không dùng ease curves, không dùng linear
Card enter
type: spring · stiffness: 300 · damping: 24
Page content, list items
Tap feedback
scale: 0.97 · duration: 0.08s
Buttons, interactive rows
Sheet open
y: 100% → 0 · spring · damping: 32
Bottom sheets, drawers
Stagger
staggerChildren: 0.08s
Grid / list of cards
Nav indicator
layout · spring · stiffness: 400 · damping: 30
Bottom nav pill
Hero entrance
y: 20 → 0 · opacity: 0 → 1 · spring
Section headings

Tính năng cốt lõi

12 module chính, thiết kế cho người Việt đi du lịch nhóm hoặc solo.

✈️

Trip Management

Tạo, chỉnh sửa và chia sẻ chuyến đi với thành viên. Mỗi trip có mã riêng để join bằng QR hoặc link.

💸

Expense Splitting

Chia tiền equal/custom, payer tracking. AI tính debt settlement tối ưu với thuật toán graph minimization.

🤖

AI Itinerary

Nhập điểm đến + ngân sách → Gemini sinh lịch trình chi tiết theo ngày, kèm gợi ý địa điểm và thời gian.

📷

Bill Scanner (OCR)

Chụp ảnh hóa đơn → AI đọc và điền tự động vào form expense. Hỗ trợ tiếng Việt và nhiều định dạng.

🎫

Ticket Storage

Quét vé máy bay, tàu xe, khách sạn. Lưu trữ và hiển thị trong timeline chuyến đi.

🌤️

Weather Integration

Dự báo thời tiết theo lịch trình. AI đề xuất điều chỉnh kế hoạch khi thời tiết xấu.

💬

Trip Chat (AI)

Chat nhóm riêng cho từng trip. AI assistant trả lời câu hỏi về địa điểm, tiền tệ, văn hoá địa phương.

🧳

Packing List

Danh sách đồ thông minh, chia sẻ với nhóm và đánh dấu đã chuẩn bị xong từng mục.

🌍

Community

Khám phá trip templates từ cộng đồng. Like, import activities vào trip của mình. Xem công khai không cần đăng nhập.

💱

Currency

Tỉ giá thời gian thực, chuyển đổi chi phí về VNĐ tự động khi nhập expense nước ngoài.

📊

Statistics

Biểu đồ chi tiêu theo ngày, danh mục, thành viên. Export PDF báo cáo hoàn chỉnh.

📦

Storage

Lưu file, ảnh, tài liệu chuyến đi. Tích hợp Supabase + Cloudinary CDN với auto-compress.

Tech Stack

Mọi quyết định kỹ thuật đều có lý do — từ Next.js App Router đến Upstash Redis serverless-safe cache.

Next.js 15

Frontend

App Router, Server Components, streaming SSR, edge-ready middleware

React 19

Frontend

Concurrent rendering, useTransition, Suspense boundaries

Tailwind CSS 3

Frontend

Utility-first, JIT, custom design tokens via CSS custom properties

Framer Motion 12

Frontend

Spring physics animations, layout transitions, drag gestures

Radix UI

Frontend

Unstyled, accessible primitives — Dialog, Select, Tooltip và hơn 20 component

React Hook Form + Zod

Frontend

Type-safe form validation với schema inference, zero re-renders

App Architecture

Next.js App Router · 4 route groups · versioned API · dual database

Route Groups
app/(main)/auth-gated
Protected: home, trips, settings, join, community
app/(auth)/public
Sign in, sign up, OTP verify, create passcode
app/(public)/public
Welcome, terms, privacy, about-me, donate
app/developer/public
Developer portal — design system, API docs
Data Layer
MongoDB
Primary: trips, activities, expenses, users, media, app_updates
PostgreSQL + Prisma
OTP sessions, verification tokens — type-safe
Upstash Redis
Cache (30s TTL), rate limiting per IP/email
Supabase Storage
Binary files: receipts, documents, attachments
Cloudinary CDN
Images/video: auto-compress, WebP/AVIF transforms
Auth Flow
1
Nhập email
Validated, autocomplete suggestions, rate-limited
2
Gửi OTP
6-digit code qua Nodemailer, TTL 10 phút
3
Verify OTP
Check PostgreSQL, mark used (one-time)
4
Tạo passcode
4-digit PIN, bcrypt hashed, confirm step
Returning user
Email → keypad 4 số → NextAuth JWT session
👤
Guest mode
Cookie session, merge sang account khi đăng ký
🔑 API Access

Đăng ký để sử dụng PineCoco API

API được mở cho third-party developers thông qua chương trình Developer Preview. Đăng ký để nhận API key và tích hợp dữ liệu chuyến đi vào ứng dụng của bạn.

01
📝

Tạo tài khoản

Đăng ký tài khoản PineCoco tại pinecoco.io.vn với email của bạn.

Đăng ký miễn phí
02
📋

Submit yêu cầu

Điền form đăng ký API với mô tả use case, tên ứng dụng và URL dự kiến.

Gửi form
03

Nhận API Key

Chúng tôi review và cấp API key qua email trong vòng 1–3 ngày làm việc.

Trong 1–3 ngày
04
🚀

Bắt đầu tích hợp

Dùng API key trong header Authorization: Bearer <key> cho mọi request.

Xem API Docs ↓
Authentication Header
Gắn vào tất cả API requests cần xác thực
Bearer Token
// HTTP Header
Authorization: Bearer pc_live_xxxxxxxxxxxxxxxxxxxx

// Fetch example
const res = await fetch("https://pinecoco.io.vn/api/v2/trips", {
  headers: {
    "Authorization": "Bearer pc_live_xxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
});

// Base URL
https://pinecoco.io.vn/api/{version}/{endpoint}
Developer Preview
Miễn phí
  • 1,000 requests / ngày
  • Truy cập v1 + v2
  • Rate limit: 60 req/min
  • Không dùng thương mại
Đăng ký ngay
Production
Liên hệ
  • Unlimited requests
  • Truy cập v1 + v2 + v3 AI
  • SLA 99.9% uptime
  • Hỗ trợ thương mại
Liên hệ team
Enterprise
Custom
  • Dedicated infrastructure
  • White-label options
  • Custom AI models
  • On-premise deployment
Thảo luận

API Reference

Base URL: https://pinecoco.io.vn/api ·  JSON request/response  ·  JWT Bearer auth

Auth level:PublicUserTrip MemberTrip OwnerAdmin

UI Patterns

Các kỹ thuật thiết kế đặc trưng làm nên trải nghiệm PineCoco.

Glass Morphism

CSS

Hai lớp glass: enhanced-glass-card cho cards (blur 24px), glass-header cho nav (blur 32px). rgba fill 80–92%, thin white ring border.

css
/* enhanced-glass-card */
background: rgba(22,22,22,0.80);
backdrop-filter: blur(24px);
border: 1px solid rgba(255,255,255,0.08);
box-shadow: 0 8px 32px rgba(0,0,0,0.24);

/* glass-header */
background: rgba(20,20,20,0.92);
backdrop-filter: blur(32px);

Spring Animation

Framer Motion

Tất cả transitions dùng spring physics, không ease curve. Cards bay từ y:20, opacity:0. Stagger children 0.08s, tap scale 0.97.

framer motion
const itemVariants = {
  hidden: { y: 20, opacity: 0 },
  visible: {
    y: 0, opacity: 1,
    transition: {
      type: "spring",
      stiffness: 300, damping: 24
    }
  }
}

// Container: staggerChildren: 0.08

Nav Pill Geometry

Math

Pill indicator tính chính xác bằng cách chia navWidth / ITEM_COUNT, đảm bảo khớp flex-1 distribution.

math
const itemWidth = navWidth / ITEM_COUNT;
const pillWidth = itemWidth - 8;

const getPillLeft = (idx: number) => {
  const center = (idx + 0.5) * itemWidth;
  return center - pillWidth / 2;
};

// getIndexFromPosition
Math.floor(relativeX / (rect.width / ITEM_COUNT))

Haptic Feedback

Web Vibration API

8 haptic patterns: tap, selection, long-press, success, warning, error, scan-success, pin-complete. Silent no-op trên iOS/Desktop.

web vibration api
const PATTERNS = {
  tap: 8,
  selection: 4,
  "long-press": 18,
  "scan-success": [10, 30, 10],
  "pin-complete": [12, 40, 12, 40, 12],
  success: [8, 25, 18],
  warning: [25, 50, 25],
  error: [40, 60, 40, 60, 40],
};

Edge Middleware Guard

Next.js Edge

Middleware tại edge trước mọi request. Check JWT, guest cookie, public routes — không DB call.

next.js edge
// Chặn experimental routes
if (pathname.startsWith("/experimental")) {
  return NextResponse.redirect(new URL("/", req.url))
}

const token = await getToken({ req, secret });
const isExpired = token?.exp * 1000 < Date.now();
const hasValidToken = token && !isExpired;

if (!hasValidToken && !isPublicRoute)
  return NextResponse.redirect("/welcome")

API Cache Strategy

Upstash Redis

GET requests cache 30s cross-instance serverless-safe. POST/PATCH/DELETE tự động invalidate cache liên quan.

upstash redis
// lib/api.ts
async get<T>(endpoint: string): Promise<T> {
  const key = `pinecoco:api:${endpoint}`;
  const cached = await cacheGet<T>(key);
  if (cached !== null) return cached;

  const data = await fetchAPI(endpoint);
  await cacheSet(key, data, 30); // 30s TTL
  return data as T;
}

Sẵn sàng tích hợp PineCoco?

Đăng ký nhận API key, đọc tài liệu đầy đủ, hoặc mở thẳng ứng dụng.

Đăng ký API Key →API Reference ↑Mở app ↗