Ensoul Digital Space 灵境遗珍

Your personal sanctuary for treasured memories and awakened spirits.

Overview

Ensoul Digital Space is a Next.js 15 application that allows users to:

• Upload photos of treasured items
• AI-powered image processing (cutout)
• Generate unique spirit companions through a questionnaire
• Engage in mystical Q&A conversations with their spirit (Book of Answers)

Tech Stack

• Frontend: Next.js 15, React 19, TypeScript
• Styling: Tailwind CSS
• Database: SQLite with Prisma ORM
• Authentication: JWT-based with HTTP-only cookies
• AI Integration: OpenAI API (optional)

Getting Started

Prerequisites

• Node.js 18+
• npm or yarn

Installation

1. Clone the repository:

git clone <repository-url>
cd ensoul-digital-space

2. Install dependencies:

npm install

3. Set up environment variables:

cp .env.example .env.local

Edit .env.local and configure:

• DATABASE_URL - SQLite database path (default: file:./dev.db)
• JWT_SECRET - A secure random string (min 32 characters)
• OPENAI_API_KEY - (Optional) For AI-powered story generation

4. Initialize the database:

npm run db:push

5. Start the development server:

npm run dev

Visit http://localhost:3000 to see the app.

Project Structure

ensoul-digital-space/
├── app/                    # Next.js App Router
│   ├── api/               # API Routes (Backend)
│   │   ├── auth/          # Authentication endpoints
│   │   ├── items/         # Items CRUD endpoints
│   │   └── ai/            # AI endpoints (story, image processing)
│   ├── home/              # Home page
│   ├── login/             # Login/Register page
│   ├── profile/           # User profile page
│   ├── upload/            # Item upload wizard
│   ├── item/[id]/         # Item detail page
│   ├── onboarding/        # New user onboarding
│   ├── layout.tsx         # Root layout
│   ├── page.tsx           # Splash page
│   └── globals.css        # Global styles
├── components/            # React components
│   ├── providers/         # Context providers
│   └── ui/                # UI components
├── lib/                   # Utilities and configurations
│   ├── auth.ts            # Authentication utilities
│   ├── ai.ts              # AI integration
│   ├── db.ts              # Database client
│   ├── types.ts           # TypeScript types
│   └── utils.ts           # Helper functions
├── prisma/
│   └── schema.prisma      # Database schema
└── public/                # Static assets

API Endpoints

Authentication

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• POST /api/auth/logout - User logout
• GET /api/auth/me - Get current user
• PATCH /api/auth/onboarding - Update onboarding status

Items

• GET /api/items - List user's items
• POST /api/items - Create new item
• GET /api/items/[id] - Get item details
• PATCH /api/items/[id] - Update item
• DELETE /api/items/[id] - Delete item
• GET /api/items/[id]/chat - Get chat history
• POST /api/items/[id]/chat - Ask a question (Book of Answers)

AI

• POST /api/ai/story - Generate spirit story
• POST /api/ai/process-image - Process image (AI cutout)
• POST /api/ai/answer - Get Book of Answers response

Features

User Authentication

• Username/password registration and login
• Remember me functionality (30-day session)
• Secure password hashing with bcrypt
• JWT-based session management

Item Management

• Upload and process images
• AI-powered object detection (mock implementation)
• Questionnaire-based spirit generation
• 6 unique spirit types

Book of Answers

• Mystical Q&A experience
• Short, philosophical responses (≤10 Chinese characters)
• Bilingual answers (Chinese + English)
• Conversation history

Scripts

npm run dev        # Start development server
npm run build      # Build for production
npm run start      # Start production server
npm run lint       # Run ESLint
npm run db:push    # Push schema to database
npm run db:studio  # Open Prisma Studio

Environment Variables

Variable	Description	Required
DATABASE_URL	SQLite database path	Yes
JWT_SECRET	Secret for JWT signing	Yes
OPENAI_API_KEY	OpenAI API key	No
SESSION_EXPIRY_DAYS	Session duration in days	No (default: 30)
NEXT_PUBLIC_APP_URL	Application URL	No

Development Notes

AI Integration

The app includes optional OpenAI integration for:

• Generating spirit stories based on questionnaire answers
• Generating contextual Book of Answers responses

If OPENAI_API_KEY is not set, the app uses fallback mock implementations.

Database

The app uses SQLite with Prisma for simplicity. For production, consider switching to PostgreSQL or MySQL by updating the Prisma schema.

License

MIT