chore: initialize monorepo wrapper

README.md

@@ -0,0 +1,105 @@
+# DUBSOFT Monorepo
+
+This repository is a root wrapper around two child applications:
+
+- `POCSite`: Next.js application with Prisma-backed persistence
+- `POCGraphGen`: Bun/TypeScript pipeline service
+
+The stack is orchestrated from the root with Docker Compose and runs all services on a shared Docker network:
+
+- `poc-site`: web app on `http://localhost:3000`
+- `poc-graph-gen`: pipeline service on `http://localhost:3001`
+- `poc-db`: PostgreSQL database on `localhost:5432`
+
+## Repository Layout
+
+```text
+.
+├── POCGraphGen/
+├── POCSite/
+├── .env.example
+├── .gitmodules
+└── compose.yml
+```
+
+## Prerequisites
+
+- Docker
+- Docker Compose
+- Git
+
+## Setup
+
+1. Create a local environment file:
+
+```bash
+cp .env.example .env
+```
+
+2. Edit `.env` and set at minimum:
+
+- `ENCRYPTION_KEY`
+- one LLM provider key for `POCGraphGen` such as `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, or `ANTHROPIC_API_KEY`
+
+3. Start the stack:
+
+```bash
+docker compose up --build
+```
+
+## Services
+
+### `poc-site`
+
+- Source: `POCSite/`
+- Host URL: `http://localhost:3000`
+- Connects to Postgres through `DATABASE_URL`
+- Calls the pipeline service over the internal Docker network
+
+### `poc-graph-gen`
+
+- Source: `POCGraphGen/`
+- Host URL: `http://localhost:3001`
+- Internal service URL from other containers: `http://poc-graph-gen:3000`
+- Requires at least one configured LLM provider credential
+
+### `poc-db`
+
+- Image: `postgres:16-alpine`
+- Host port: `5432`
+- Data is persisted in the `poc-db-data` Docker volume
+
+## Common Commands
+
+Start in the foreground:
+
+```bash
+docker compose up --build
+```
+
+Start in the background:
+
+```bash
+docker compose up --build -d
+```
+
+Stop the stack:
+
+```bash
+docker compose down
+```
+
+Stop the stack and remove volumes:
+
+```bash
+docker compose down -v
+```
+
+## Git Submodules
+
+Both child projects are registered as git submodules from the root repository.
+
+Current note:
+- the submodule URLs are local paths right now, so this setup is correct for this machine but not yet portable for fresh clones from another machine
+
+If you later add remotes for `POCSite` and `POCGraphGen`, update `.gitmodules` to point at those repository URLs.