feat: setup domain core db communication

.gitignore

@@ -39,3 +39,5 @@ yarn-error.log*
 # typescript
 *.tsbuildinfo
 next-env.d.ts
+
+/lib/generated/prisma

DATABASE.md

@@ -0,0 +1,114 @@
+# Database Setup and Migrations
+
+## Overview
+
+PostgreSQL 16 with Prisma ORM. **Migrations auto-apply on server startup** in all environments.
+
+## Setup
+
+**Using Docker (recommended):**
+
+```bash
+./docker-manage.sh up development
+```
+
+- Database runs automatically in Docker
+- No `.env` file needed - `DATABASE_URL` is set in `docker-compose.yml`
+- Migrations run on startup
+
+**Using Prisma Studio GUI:**
+
+1. Ensure Docker database is running: `./docker-manage.sh up development`
+2. Create `.env` file in project root with `DATABASE_URL` from
+   `docker/development/docker-compose.yml`
+3. Run: `npm run db:studio`
+
+## Quick Start
+
+```bash
+# Development
+./docker-manage.sh up development
+
+# Production/Staging
+./docker-manage.sh up production
+./docker-manage.sh up staging
+```
+
+## How Migrations Work
+
+**Automatic on startup:**
+
+- **Production/Staging**: Crashes if migration fails (safe)
+- **Development**: Continues if migration fails (non-blocking)
+
+**Creating migrations:**
+
+```bash
+# 1. Edit prisma/schema.prisma
+# 2. Create migration file
+npm run db:migrate
+
+# 3. Restart server - migration auto-applies
+./docker-manage.sh restart development
+```
+
+## Database Scripts
+
+| Script        | Purpose                           |
+| ------------- | --------------------------------- |
+| `db:migrate`  | Create new migration file         |
+| `db:studio`   | Open Prisma Studio GUI            |
+| `db:reset`    | Reset database (⚠️ destroys data) |
+| `db:generate` | Regenerate Prisma Client          |
+
+## Common Tasks
+
+**View database:**
+
+```bash
+# Prisma Studio (GUI) - requires .env file with DATABASE_URL
+npm run db:studio
+# Opens at http://localhost:5555
+```
+
+Alternatively, use VS Code PostgreSQL extensions with connection:
+
+- Host: `localhost`, Port: `5432`, Database: `memo_dev`
+- Username: `memo_user`, Password: `memo_password`
+
+**Check migration status:**
+
+```bash
+npx prisma migrate status
+```
+
+**Reset database (dev only):**
+
+```bash
+npm run db:reset
+```
+
+## Schema
+
+See [prisma/schema.prisma](prisma/schema.prisma) for the complete schema.
+
+Models: User, Competency, CompetencyRelationship, LearningResource, CompetencyResourceLink
+
+## Troubleshooting
+
+**"Database schema is not in sync"**
+
+```bash
+npm run db:migrate
+```
+
+**"Prisma Client out of sync"**
+
+```bash
+npm run db:generate
+```
+
+**Production migration failed**
+
+- Check `DATABASE_URL` environment variable
+- View logs: `./docker-manage.sh logs production`

DOMAIN_CORE.md

@@ -0,0 +1,213 @@
+# Domain Core Architecture
+
+This project uses a layered architecture where **only the domain core communicates with the
+database**.
+
+## Architecture Flow
+
+```
+Client Side
+    ↓
+Server Actions (app/actions/)
+    ↓
+Service Layer (lib/services/)
+    ↓
+Repository Interface (lib/repositories/dc_interface.ts)
+    ↓
+Repository Implementation (lib/repositories/dc_user_repo.ts) ← ONLY layer that touches DB
+    ↓
+Prisma Client (lib/prisma.ts)
+    ↓
+PostgreSQL Database
+```
+
+## How It Works
+
+### 1. Domain Layer (`lib/domain/domain_core.ts`)
+
+Pure entities and input types. No database dependencies.
+
+```typescript
+export interface Competency {
+  id: string;
+  title: string;
+  description: string | null;
+  createdAt: Date;
+}
+
+export interface CreateCompetencyInput {
+  title: string;
+  description?: string;
+}
+```
+
+### 2. Repository Interface (`lib/repositories/dc_interface.ts`)
+
+Contract definition. No implementation.
+
+```typescript
+export interface CompetencyRepository {
+  create(data: CreateCompetencyInput): Promise<Competency>;
+  findById(id: string): Promise<Competency | null>;
+  findAll(): Promise<Competency[]>;
+}
+```
+
+### 3. Repository Implementation (`lib/repositories/dc_user_repo.ts`)
+
+Prisma implementation. **ONLY this layer touches the database.**
+
+```typescript
+export class PrismaCompetencyRepository implements CompetencyRepository {
+  async create(data: CreateCompetencyInput): Promise<Competency> {
+    return await prisma.competency.create({ data });
+  }
+}
+
+export const competencyRepository = new PrismaCompetencyRepository();
+```
+
+### 4. Service Layer (`lib/services/`)
+
+Business logic and validation.
+
+```typescript
+export class CompetencyService {
+  constructor(private readonly repository: CompetencyRepository) {}
+
+  async createCompetency(data: CreateCompetencyInput) {
+    return await this.repository.create(data);
+  }
+}
+
+export const competencyService = new CompetencyService(competencyRepository);
+```
+
+### 5. Server Actions (`app/actions/`)
+
+Exposes operations to Client Side.
+
+```typescript
+'use server';
+
+import { competencyService } from '@/lib/services/competency-service';
+
+export async function createCompetencyAction(formData: FormData) {
+  try {
+    const title = formData.get('title') as string;
+    const competency = await competencyService.createCompetency({ title });
+    return { success: true, competency };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+```
+
+## Usage from Client Side
+
+### Server Components (Default)
+
+```tsx
+import { getAllCompetenciesAction } from '@/app/actions/competencies';
+
+export default async function CompetenciesPage() {
+  const { success, competencies } = await getAllCompetenciesAction();
+
+  if (!success) return <div>Error loading competencies</div>;
+
+  return (
+    <div>
+      {competencies?.map(comp => (
+        <div key={comp.id}>
+          <h2>{comp.title}</h2>
+          <p>{comp.description}</p>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Client Components
+
+```tsx
+'use client';
+
+import { createCompetencyAction } from '@/app/actions/competencies';
+import { useState } from 'react';
+
+export default function CreateCompetencyForm() {
+  const [message, setMessage] = useState('');
+
+  async function handleSubmit(formData: FormData) {
+    const result = await createCompetencyAction(formData);
+    setMessage(result.success ? 'Created!' : result.error);
+  }
+
+  return (
+    <form action={handleSubmit}>
+      <input name="title" placeholder="Title" required />
+      <textarea name="description" placeholder="Description" />
+      <button type="submit">Create</button>
+      {message && <p>{message}</p>}
+    </form>
+  );
+}
+```
+
+## Connecting to an API
+
+To expose data through an API endpoint:
+
+```typescript
+// app/api/competencies/route.ts
+import { competencyService } from '@/lib/services/competency-service';
+import { NextResponse } from 'next/server';
+
+export async function GET() {
+  try {
+    const competencies = await competencyService.getAllCompetencies();
+    return NextResponse.json({ success: true, competencies });
+  } catch (error) {
+    return NextResponse.json({ success: false, error: error.message }, { status: 500 });
+  }
+}
+
+export async function POST(request: Request) {
+  try {
+    const body = await request.json();
+    const competency = await competencyService.createCompetency(body);
+    return NextResponse.json({ success: true, competency });
+  } catch (error) {
+    return NextResponse.json({ success: false, error: error.message }, { status: 500 });
+  }
+}
+```
+
+## Rules
+
+### ✅ DO
+
+- Use Server Actions from Client Side
+- Add business logic in Service layer
+- Use repository interfaces in services
+- Call services from API routes for external APIs
+
+### ❌ DON'T
+
+- Never import `prisma` in Client Side/services/API routes
+- Never skip layers (call repository directly from actions/routes)
+- Never put business logic in Server Actions or API routes
+- Never put database queries outside repositories
+
+## Existing Entities
+
+Full CRUD implementations available:
+
+- **User** - [actions/users.ts](app/actions/users.ts)
+- **Competency** - [actions/competencies.ts](app/actions/competencies.ts)
+- **LearningResource** - [actions/learning-resources.ts](app/actions/learning-resources.ts)
+- **CompetencyRelationship** -
+  [actions/competency-relationships.ts](app/actions/competency-relationships.ts)
+- **CompetencyResourceLink** -
+  [actions/competency-resource-links.ts](app/actions/competency-resource-links.ts)

Dockerfile

@@ -16,7 +16,8 @@ CMD ["npm", "run", "dev"]
 # Dependencies stage (for production)
 FROM base AS deps
 COPY package.json package-lock.json ./
-RUN npm ci --only=production --legacy-peer-deps
+RUN npm ci --only=production --legacy-peer-deps && \
+    npm install prisma --legacy-peer-deps
 
 # Builder stage
 FROM base AS builder
@@ -37,5 +38,8 @@ COPY --from=builder /app/public ./public
 COPY --from=builder /app/package.json ./package.json
 COPY --from=builder /app/next.config.ts ./next.config.ts
 
+# Copy Prisma schema and migrations for runtime migration execution
+COPY --from=builder /app/prisma ./prisma
+
 EXPOSE 3000
 CMD ["npm", "start"]

README.md

@@ -192,13 +192,20 @@ See [DOCKER.md](DOCKER.md) for detailed Docker setup information. See
 7. Push to the branch: `git push origin feature/amazing-feature`
 8. Open a Pull Request
 
-## 📚 Learn More
+## 📚 Documentation
 
-To learn more about the technologies used:
+### Project Documentation
+
+- [Database Setup & Migrations](DATABASE.md) - Database management, migrations, and Prisma scripts
+- [Docker Setup](DOCKER.md) - Detailed Docker configuration and deployment
+- [Claude Code Guide](CLAUDE.md) - Project conventions and AI assistant usage
+
+### External Resources
 
 - [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API
 - [Docker Documentation](https://docs.docker.com/) - containerization platform
 - [PostgreSQL Documentation](https://www.postgresql.org/docs/) - database system
+- [Prisma Documentation](https://www.prisma.io/docs) - ORM and database toolkit
 
 ## 🆘 Troubleshooting