content-factory/tasks/001-dockerized-monorepo-foundation.md

Task 001: Dockerized Monorepo Foundation

Development description: Create the deployable project foundation for the AI Content Pipeline with backend, frontend, runner, shared contracts, and local infrastructure booting through one Docker Compose command.

Implementation Details

• Create a monorepo layout:
  • apps/backend for FastAPI.
  • apps/frontend for Next.js.
  • apps/runner for the agent runner service.
  • packages/shared for shared schemas and generated clients.
  • infra/docker for local infra configuration.
• Add docker-compose.yml with services for frontend, backend, runner, Postgres, Redis, and S3-compatible object storage such as MinIO.
• Add health endpoints:
  • Backend: GET /health.
  • Runner: GET /health.
  • Frontend route: /health.
• Add a root developer command such as make dev or pnpm dev:stack that starts the full stack.
• Add .env.example with local-only defaults and no secrets.

Public Interface

• docker compose up --build starts the stack.
• GET http://localhost:<backend-port>/health returns backend health.
• GET http://localhost:<runner-port>/health returns runner health.
• GET http://localhost:<frontend-port>/health returns frontend health.

Acceptance Criteria

• TDD pre-requirement: before implementation, define the public health interfaces and write one failing stack/health check test first; proceed one red-green-refactor cycle at a time and record evidence in Result.
• A clean checkout can build and start the stack with one documented command.
• Backend, frontend, runner, Postgres, Redis, and object storage containers start without manual setup.
• Health checks pass from outside the containers.
• Backend can connect to Postgres, Redis, and object storage using environment variables.
• No real credentials are committed.

Verification

• Run docker compose up --build.
• Run health checks against backend, frontend, and runner.
• Run a smoke test that verifies backend connectivity to Postgres, Redis, and object storage.

Result

• Status: Completed; public health smoke is green.
• TDD plan:
  • Public contract documented in docs/public-health-interfaces.md.
  • First vertical Red test added at tests/smoke/public-health.sh.
  • The test starts the stack with docker compose -f docker-compose.yml up --build -d.
  • The test verifies only public HTTP surfaces:
    • Backend process health: GET http://localhost:8000/health.
    • Runner health: GET http://localhost:8010/health.
    • Frontend health: GET http://localhost:3000/health.
    • Backend dependency smoke: GET http://localhost:8000/health/dependencies for Postgres, Redis, and object storage connectivity.
  • Implementation agent should make this single test green before adding the next public behavior test.
• Red evidence:
  • Command: bash tests/smoke/public-health.sh.
  • Actual output:

    Starting stack with docker compose...
    open /Users/gavrilovdev/tmp/pupline/docker-compose.yml: no such file or directory
    

  • Result: failed as expected because the Docker Compose stack and service health implementations do not exist yet.
• Green evidence:
  • Command: bash tests/smoke/public-health.sh.
  • Final observed output excerpt:

    Starting stack with docker compose...
    ...
    #22 106.2 found 0 vulnerabilities
    ...
    pupline-frontend  Built
    pupline-runner  Built
    pupline-backend  Built
    ...
    Container pupline-backend-1  Started
    Container pupline-frontend-1  Started
    backend health ok
    runner health ok
    frontend health ok
    backend dependencies ok
    public health smoke ok
    

• Refactor notes:
  • Backend implemented as FastAPI with /health and /health/dependencies.
  • Runner health uses a minimal stdlib HTTP service to avoid unnecessary image dependencies for Task 001.
  • Frontend uses Next.js App Router under apps/frontend/src/app; FSD placeholder layers live under apps/frontend/src/processes, src/pages, src/widgets, src/features, src/entities, and src/shared.
  • Frontend pins Next.js 16.2.6 and overrides PostCSS to 8.5.14; Docker build npm install reported found 0 vulnerabilities.
• Verification output:
  • Command: python3 -m py_compile apps/backend/src/presentation/main.py apps/backend/src/infrastructure/dependencies.py apps/runner/src/presentation/main.py. Output: no output, exit code 0.
  • Command: docker compose config --quiet. Output: no output, exit code 0.
  • Command: bash tests/smoke/public-health.sh. Output:

    backend health ok
    runner health ok
    frontend health ok
    backend dependencies ok
    public health smoke ok