# 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

- [x] Task 1: Initialize TanStack Start project (AC: 1)
  - [x] Create new TanStack Start project with `pnpm create @tanstack/start`
  - [x] Configure `tsconfig.json` with strict mode enabled
  - [x] Configure path aliases (`@/` pointing to `src/`)
  - [x] Verify TypeScript strict compilation works

- [x] Task 2: Setup Docker environment (AC: 2, 7)
  - [x] Create `docker/` directory
  - [x] Create `docker/Dockerfile` with multi-stage build (builder + runner)
  - [x] Create `docker/docker-compose.yml` with app and postgres services
  - [x] Create `docker/docker-compose.dev.yml` for local development (postgres only)
  - [x] Configure PostgreSQL 16-alpine with healthcheck
  - [x] Test database connectivity

- [ ] Task 3: Configure Prisma ORM (AC: 3)
  - [x] Install Prisma dependencies (`prisma`, `@prisma/client`)
  - [x] Initialize Prisma with `pnpm prisma init`
  - [x] 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:**

```yaml
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]

```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

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

**Endpoint:** `GET /api/health`

**Response:**

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

**Implementation avec TanStack Start:**

```typescript
// 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_