121 lines
7.6 KiB
Markdown
121 lines
7.6 KiB
Markdown
# ProjectBrain
|
|
|
|
**A self-hosted operating workspace for software projects, from durable context to validated delivery.**
|
|
|
|
ProjectBrain keeps project knowledge, connected repository evidence, work requests, human decisions and delivery results together. Its normal flow starts with a plain-language request and ends with an understandable result and the evidence behind it. Technical work graphs, executors and release details remain available when needed.
|
|
|
|
## The project journey
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
A[Project context and repository] --> B[Request and constraints]
|
|
B --> C[Plan and governed execution]
|
|
C --> D[Validate and recover]
|
|
D --> E[Result and evidence]
|
|
C --> F[Human decision when required]
|
|
F --> C
|
|
```
|
|
|
|
## What it provides
|
|
|
|
- Portfolio orientation: attention, active work, recovery and recent delivery across projects.
|
|
- Project overview, request workspace, attention inbox, results and chronological activity.
|
|
- Repository intake and analysis, project knowledge with provenance/freshness/conflict signals, and supplementary source libraries.
|
|
- Durable work graphs with dependencies, priorities, bounded execution recovery and explicit completion criteria.
|
|
- Governed Gitea execution using deterministic work branches, exact-head Actions evidence, pull requests and controlled merges.
|
|
- Review, evidence, release and handoff surfaces that distinguish implemented, validated, merged, deployed and runtime-verified work.
|
|
- Session/context packs and MCP integration for coordinating external reasoning and execution clients.
|
|
- Database-backed persistence with Prisma/PostgreSQL and separate analysis/reconciliation workers.
|
|
|
|
Capabilities depend on configured integrations and verified execution paths. A reachable endpoint, mock success or passing build does not establish production deployment capability. High-risk or destructive work remains a human decision boundary.
|
|
|
|
## Start with a preview
|
|
|
|
The frontend has a development-only mock client for exploring the product without a database or repository credentials:
|
|
|
|
```bash
|
|
pnpm install --frozen-lockfile
|
|
VITE_PROJECTBRAIN_CLIENT_MODE=mock pnpm dev
|
|
```
|
|
|
|
Open the Vite URL shown in the terminal. In PowerShell, set `$env:VITE_PROJECTBRAIN_CLIENT_MODE='mock'` before `pnpm dev`. Mock state is synthetic development data and is not production readiness evidence. Production builds reject explicit mock mode.
|
|
|
|
## Interface preview
|
|
|
|
These screenshots show the existing synthetic WideFrog/Nebula development fixtures. The current product UI includes Dutch labels; this README is in English. No live project inventory, repository credentials or private runtime data is shown.
|
|
|
|
|
|
|
|
|
|
|
|
## Deploy your own instance
|
|
|
|
Requirements: **Node.js 24**, **pnpm 11.5.2**, Docker Compose and persistent PostgreSQL storage.
|
|
|
|
```bash
|
|
git clone https://gitea.itworx.tech/Jens/projectbrain-Public.git
|
|
cd projectbrain-Public
|
|
cp .env.example .env
|
|
# Configure independent database, owner-login and authentication secrets.
|
|
docker compose up --build
|
|
```
|
|
|
|
The default web port is `1209`. The integrated stack runs the React frontend behind nginx, Fastify API, PostgreSQL and background workers. Production uses `PROJECTBRAIN_DATA_SOURCE=database` and `VITE_PROJECTBRAIN_CLIENT_MODE=real`; an empty frontend API URL uses the same-origin `/api` proxy. The server rejects placeholder authentication secrets in production.
|
|
|
|
Persist the database and application state independently of the checkout. Before upgrading, back up state, review Prisma migrations and verify authenticated workflows after deployment. The single-container Unraid build remains available in `Dockerfile.unraid`; it is a bootstrap/packaging option, not evidence that a live managed target has been promoted.
|
|
|
|
The canonical private deployment uses a separate Deployment Controller: reviewed merges, validation on the exact merge SHA, immutable promotion, controller receipts and runtime checks. Public source synchronization does not deploy that private target or replace its release procedure.
|
|
|
|
## From a request to verified delivery
|
|
|
|
Create a project, add one bounded request and inspect its generated work graph. Review repository, branch and revision context before enabling a Gitea write integration. Track implementation evidence, validation, merge, deployment and runtime verification as separate outcomes.
|
|
|
|
The mock preview is useful for navigation and product evaluation. It does not persist real delivery evidence or execute repository work. A successful public-source sync publishes reviewed source; it does not deploy ProjectBrain or the projects it tracks.
|
|
|
|
## Connect repositories and execution
|
|
|
|
Set Gitea service credentials in the backend environment. Give the read connector only the intended repository access; configure the separate write token only when governed execution is required. Keep tokens, webhook secrets and MCP service credentials out of frontend builds and source control.
|
|
|
|
Create or import a project, connect its repository, review the known context and capabilities, then submit a request with clear scope and constraints. Use **Your attention** for genuine product/risk decisions, **Results** for completed work and evidence, and **Activity** for recovery and history. Repository evidence remains the primary technical source; additional sources supply requirements or references outside that repository.
|
|
|
|
Optional Microsoft Entra login requires a registered Web callback and server-side tenant/client credentials; see [Entra configuration](docs/MICROSOFT_ENTRA_LOGIN.md). MCP is opt-in and requires its own authentication and capability policy.
|
|
|
|
## Develop and validate
|
|
|
|
```bash
|
|
pnpm install --frozen-lockfile
|
|
pnpm dev
|
|
# In another terminal:
|
|
pnpm --filter projectbrain-api run dev
|
|
```
|
|
|
|
For local database work, start `docker compose -f docker-compose.dev.yml up -d postgres`, set a local `DATABASE_URL`, generate Prisma and apply migrations through the backend scripts. The supplied development database credentials and exposed database port are for isolated development only.
|
|
|
|
```bash
|
|
pnpm run typecheck
|
|
pnpm run lint
|
|
pnpm run test
|
|
pnpm run build
|
|
pnpm --filter projectbrain-api run typecheck
|
|
pnpm --filter projectbrain-api run test
|
|
```
|
|
|
|
Database/browser release qualification needs disposable infrastructure and authenticated flows. Fixture tests alone prove development behavior. See the [product contract](docs/UX_AUTONOMY_PRODUCT_CONTRACT.md) and [backend architecture decision](docs/REAL_BACKEND_ARCHITECTURE_DECISION.md) for the intended boundaries.
|
|
|
|
## Technical map
|
|
|
|
| Directory | Responsibility |
|
|
| --- | --- |
|
|
| `src/` | React product workspace, API clients and synthetic preview data |
|
|
| `backend/` | Fastify API, persistence, workers, Prisma schema and migrations |
|
|
| `packages/contracts/` | Shared typed contracts |
|
|
| `docker/` | nginx and self-hosted packaging templates |
|
|
| `e2e/` | Development browser regression tests |
|
|
| `docs/` | Selected durable product, integration and licensing documentation |
|
|
|
|
## Public source and licensing
|
|
|
|
This is the curated public source edition of ProjectBrain 0.7.1. Reviewed changes are synchronized from the private canonical repository after merges to `main`. Private Git history, internal workflows, deployment evidence, operator records and runtime credentials are not part of this distribution. Generic deployment examples must be configured for your environment.
|
|
|
|
No repository-wide software license has been selected. Public visibility does not grant reuse, modification or redistribution rights. The existing [licensing status](docs/LICENSING.md) is preserved; third-party dependency and asset terms require separate review.
|