Sidecause

Status

This repository contains the development foundation and initial App Router shell for a public-facing Next.js application. The root landing page, layout, and global styles are ready for feature development; authentication, database models, migrations, API routes, and browser workflows have not been created yet. The approved product decisions are recorded in docs/product-spec.md and docs/implementation-plan.md.

Repository map

Location	Purpose
app/	Next.js App Router shell: root layout, landing page, and global styles.
pages/	Unused; new application routes use the App Router only.
prisma/	Prisma connection and migration configuration; no product schema or migrations.
tests/unit/, tests/integration/, tests/e2e/	Planned test locations; currently empty harnesses.
scripts/smoke.sh	Isolated PostgreSQL and AIStor infrastructure smoke test.
Dockerfile, compose.yml	Development container and local PostgreSQL/AIStor services.
.github/workflows/	Pull-request quality/security checks, CodeQL, and guarded release workflow.
.agents/skills/	Repository-local operating guidance for agents.
AGENTS.md	Project-specific human/agent contribution guidance.

Getting Started

1. Install Git, Node.js 26.8.2, and Docker Desktop (or Docker Engine with the Compose plugin). Node 26 is the project’s active-LTS line; npm 11 is bundled with it.

2. Copy the local configuration template. It contains only safe local service credentials; replace AUTH_SECRET before authentication work begins.

   cp .env.example .env

3. Install exact locked dependencies.

   npm ci

4. Start local PostgreSQL on 5432 and AIStor on 9000 (console 9001).

   npm run docker:up

5. Run the available local checks.

   npm run verify
   npm run test:smoke

6. Stop services when finished. docker:down preserves local volumes; use docker compose down --volumes only when you intentionally want to discard local database and object-storage data.

   npm run docker:down

Start the App Router shell locally with npm run dev, and create a production build with npm run build. npm run test:e2e remains deferred until browser workflows exist. The app Compose profile is intentionally not started by default; use docker compose --profile app up --build when you want to run the full local stack in containers.

To install dependencies, start local services, and launch the development server in one command, run:

./scripts/dev.sh

Database migrations

Prisma is configured for PostgreSQL and reads DATABASE_URL from .env. No product schema exists yet. Once a model is approved, create and review a development migration with:

npm run prisma:migrate -- --name describe_the_change

Use npm run prisma:deploy only in a controlled deployment workflow against an approved target—never against production from a workstation.

CI and GitHub configuration

Pull requests run formatting, linting, TypeScript, the current Vitest coverage harness, Gitleaks, and CodeQL. The Next.js build is now available locally; the integration suite and Playwright suite remain deferred until their workflows exist. Configure branch protection to require those completed checks and a review.

Dependabot checks npm, Docker, and GitHub Actions dependencies weekly. Releases are intentionally blocked until a container registry and managed container host are selected. Before enabling release publishing/deployment, create a protected GitHub production environment and supply CONTAINER_REGISTRY_TOKEN, CLOUD_DEPLOY_CREDENTIALS, DATABASE_URL, OBJECT_STORAGE_*, and AUTH_* as environment-scoped secrets.

Troubleshooting

• npm ci rejects the lockfile: use Node 26.8.2 and npm 11, then retry without editing package-lock.json.
• A local port is occupied: free or remap port 5432, 9000, or 9001 before starting Compose. Update .env if you remap a service used by application code.
• Docker permission/daemon error: start Docker Desktop (or the Docker daemon) and ensure your account can run docker compose.
• Prisma reports DATABASE_URL missing: copy .env.example to .env, then run the command from the repository root.

Source references

The configuration follows the official Next.js manual installation and linting guidance, Next.js ESLint flat-config guidance, Prisma Migrate development/production workflow, Vitest V8 coverage guide, and Playwright installation guide. AIStor is used locally because the current MinIO project advises it for maintained container security updates.