dofus-manager/docs/stories/1.1.story.md

Story 1.1: Project Setup & Infrastructure

Status

Draft

Story

As a developer, I want a fully configured TanStack Start project with Docker and GitLab CI, so that I can start development with a working local environment and deployment pipeline.

Acceptance Criteria

1. TanStack Start project initialized with TypeScript strict mode
2. Docker Compose configuration with app service and PostgreSQL 16
3. Prisma configured and connected to PostgreSQL
4. shadcn/ui installed with base components (Button, Input, Card, Table)
5. Biome configured for linting and formatting
6. Gitea Actions workflow: build, lint, test stages
7. Dockerfile multi-stage pour production build
8. README avec instructions de setup local
9. Application démarre et affiche une page d'accueil "Dofus Manager"
10. Health check endpoint /api/health pour Docker healthcheck

Tasks / Subtasks

• Task 1: Initialize TanStack Start project (AC: 1)

  • Create new TanStack Start project with pnpm create @tanstack/start
  • Configure tsconfig.json with strict mode enabled
  • Configure path aliases (@/ pointing to src/)
  • Verify TypeScript strict compilation works

• Task 2: Setup Docker environment (AC: 2, 7)

  • Create docker/ directory
  • Create docker/Dockerfile with multi-stage build (builder + runner)
  • Create docker/docker-compose.yml with app and postgres services
  • Create docker/docker-compose.dev.yml for local development (postgres only)
  • Configure PostgreSQL 16-alpine with healthcheck
  • Test database connectivity

• Task 3: Configure Prisma ORM (AC: 3)

  • Install Prisma dependencies (prisma, @prisma/client)
  • Initialize Prisma with pnpm prisma init
  • Configure prisma/schema.prisma with PostgreSQL provider
  • Create src/lib/server/db.ts for Prisma client singleton
  • Create .env.example with DATABASE_URL template
  • Verify Prisma connects to database

• Task 4: Install and configure shadcn/ui (AC: 4)

  • Install Tailwind CSS 4.x
  • Initialize shadcn/ui with pnpm dlx shadcn@latest init
  • Configure components.json for path aliases
  • Install base components: Button, Input, Card, Table
  • Create src/lib/utils.ts with cn utility function
  • Install Lucide React for icons

• Task 5: Configure linting and formatting (AC: 5)

  • Install Biome (as specified in tech stack, not ESLint+Prettier)
  • Create biome.json with recommended rules
  • Add lint and format scripts to package.json
  • Verify linting works on project files

• Task 6: Setup Gitea Actions workflow (AC: 6)

  • Create .gitea/workflows/ci.yml
  • Configure test job: lint, typecheck, test
  • Configure build job: Docker image build and push
  • Configure deploy jobs (staging/production) with manual triggers
  • Add caching for pnpm store

• Task 7: Create README documentation (AC: 8)

  • Document project overview
  • Document prerequisites (Node 20, pnpm, Docker)
  • Document local development setup steps
  • Document available npm scripts
  • Document environment variables

• Task 8: Create home page (AC: 9)

  • Create src/routes/index.tsx as home page
  • Display "Dofus Manager" title
  • Add basic layout structure
  • Create src/styles/globals.css with Tailwind imports
  • Verify application starts and renders correctly

• Task 9: Create health check endpoint (AC: 10)

  • Create src/routes/api/health.ts server function
  • Return JSON { status: "ok", timestamp: Date }
  • Optionally check database connectivity
  • Verify endpoint responds at GET /api/health

• Task 10: Final verification

  • Run pnpm dev and verify app starts
  • Run pnpm lint and verify no errors
  • Run pnpm typecheck and verify no errors
  • Test Docker build locally
  • Verify PostgreSQL connection via Prisma

Dev Notes

Technology Stack [Source: architecture/3-technology-stack.md]

Frontend:

• React 19.x
• TanStack Router 1.x (type-safe routing)
• TanStack Query 5.x (server state)
• Zustand 5.x (client state)
• Tailwind CSS 4.x
• shadcn/ui (component library)
• Lucide React (icons)
• React Hook Form 7.x
• Zod 3.x (validation)

Backend:

• TanStack Start 1.x (full-stack framework)
• Prisma 6.x (ORM)
• Zod 3.x
• node-cache 5.x
• Pino 9.x (logging)

Database: PostgreSQL 16.x

DevOps:

• Docker
• Docker Compose
• Gitea Actions

Dev Tools:

• TypeScript (strict mode)
• Biome (linting & formatting - NOT ESLint+Prettier as mentioned in AC)
• Vitest (unit testing)
• Playwright (E2E testing)

Project Structure [Source: architecture/12-project-structure.md]

dofus-manager/
├── .gitea/
│   └── workflows/
│       └── ci.yml
├── docker/
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── docker-compose.dev.yml
├── prisma/
│   ├── schema.prisma
│   └── migrations/
├── public/
│   └── favicon.ico
├── src/
│   ├── components/
│   │   ├── ui/                    # shadcn/ui components
│   │   ├── layout/                # Layout components
│   │   └── shared/                # Shared components
│   ├── lib/
│   │   ├── utils.ts               # Utility functions (cn, etc.)
│   │   ├── errors.ts              # Error types
│   │   ├── client/
│   │   │   ├── query-client.ts
│   │   │   └── stores/
│   │   └── server/
│   │       ├── db.ts              # Prisma client
│   │       ├── cache.ts
│   │       └── logger.ts
│   ├── routes/
│   │   ├── __root.tsx
│   │   ├── index.tsx
│   │   └── api/
│   │       └── health.ts
│   ├── styles/
│   │   └── globals.css
│   └── app.tsx
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── .env.example
├── .gitignore
├── biome.json
├── package.json
├── tsconfig.json
├── app.config.ts
└── README.md

Docker Configuration [Source: architecture/14-deployment-architecture.md#docker-configuration]

Dockerfile (multi-stage):

• Build stage: node:20-alpine, pnpm, prisma generate, build
• Production stage: node:20-alpine, non-root user (app:nodejs), port 3000
• Entry point: node .output/server/index.mjs

Docker Compose:

• App service with DATABASE_URL, SESSION_SECRET
• PostgreSQL 16-alpine with healthcheck
• Traefik labels for reverse proxy (production)

Gitea Actions [Adapted from architecture]

Workflow file: .gitea/workflows/ci.yml

Jobs: test, build, deploy

Test job:

• runs-on: ubuntu-latest
• Steps: checkout, setup pnpm, setup node, install, lint, typecheck, test
• Cache pnpm store

Build job:

• needs: test
• Build and push Docker image
• Only on main/develop branches

Exemple de workflow:

name: CI
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "pnpm"
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm typecheck
      - run: pnpm test

  build:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop'
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/build-push-action@v5
        with:
          context: .
          file: docker/Dockerfile
          push: true
          tags: registry.example.com/dofus-manager:${{ github.sha }}

Environment Variables [Source: architecture/13-development-workflow.md#environment-variables]

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/dofus_manager?schema=public"

# App
APP_URL="http://localhost:3000"
NODE_ENV="development"

# Session
SESSION_SECRET="your-secret-key-min-32-chars"

Coding Standards [Source: architecture/17-coding-standards.md]

Key Rules:

• Type sharing: Define types in src/types/, never duplicate
• Server functions only: No direct HTTP calls (fetch, axios)
• Named exports for components (no default exports except routes)
• Use type imports: import type { X } from '...'

Naming Conventions:

• Components: PascalCase
• Component files: kebab-case or PascalCase
• Server functions: camelCase
• Types/Interfaces: PascalCase
• Constants: SCREAMING_SNAKE_CASE

Health Check Endpoint [Source: architecture/19-monitoring-observability.md]

Endpoint: GET /api/health

Response:

{
  "status": "ok",
  "timestamp": "2026-01-19T10:00:00.000Z",
  "database": "connected"
}

Implementation avec TanStack Start:

// src/routes/api/health.ts
import { createAPIFileRoute } from "@tanstack/start/api";
import { prisma } from "@/lib/server/db";

export const Route = createAPIFileRoute("/api/health")({
  GET: async () => {
    let dbStatus = "disconnected";
    try {
      await prisma.$queryRaw`SELECT 1`;
      dbStatus = "connected";
    } catch {
      dbStatus = "error";
    }

    return Response.json({
      status: "ok",
      timestamp: new Date().toISOString(),
      database: dbStatus,
    });
  },
});

Testing

Testing Standards [Source: architecture/16-testing-strategy.md]

Test Location:

• Unit tests: tests/unit/
• Integration tests: tests/integration/
• E2E tests: tests/e2e/

Testing Frameworks:

• Vitest for unit and integration tests
• Playwright for E2E tests

For this story (infrastructure setup):

• Minimal testing required
• Verify Vitest configuration works
• Verify basic test can run
• Create placeholder test file structure

Test file naming: *.test.ts for unit/integration, *.spec.ts for E2E

Change Log

Date	Version	Description	Author
2026-01-19	1.0	Initial story creation	SM Agent
2026-01-19	1.1	Gitea Actions, Biome, Health endpoint ajoutés	SM Agent

---

Dev Agent Record

Agent Model Used

To be filled by Dev Agent

Debug Log References

To be filled by Dev Agent

Completion Notes List

To be filled by Dev Agent

File List

To be filled by Dev Agent

---

QA Results

To be filled by QA Agent