Initial curated projectbrain source from 8a7b1e0651dbdab97d744cbd2e653ab3970ac6c5
This commit is contained in:
Public Source Publisher committed
commit
5aa3e8d685
700 files changed
+132801
No files matched your search
@@ -0,0 +1,114 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
Reference in new issue
Block a user