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. ESLint + Prettier configured with recommended rules
6. GitLab CI pipeline: 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"

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 GitLab CI/CD pipeline (AC: 6)

  • Create .gitlab-ci.yml with stages: test, build, deploy
  • Configure test stage: lint, typecheck, test
  • Configure build stage: Docker image build and push
  • Configure deploy stages (staging/production) with manual triggers
  • Add caching for node_modules

• 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: 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
• GitLab CI

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/
├── docker/
│   ├── Dockerfile
│   └── docker-compose.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
│   ├── 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)

GitLab CI/CD [Source: architecture/14-deployment-architecture.md#gitlab-cicd-pipeline]

Stages: test, build, deploy

Test stage:

• image: node:20-alpine
• Commands: pnpm lint, pnpm typecheck, pnpm test
• Cache node_modules

Build stage:

• image: docker:24
• Build and push Docker image to registry
• Only on main/develop branches

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

Important Discrepancy Note

AC #5 specifies "ESLint + Prettier" but the architecture documents (3-technology-stack.md) specify Biome for linting and formatting. Recommend following the architecture document and using Biome instead, as it's the project standard.

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

---

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