# 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]

```bash
# 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_