Skip to content

docs(repo): add contributor orientation guides #652

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
horacioh wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(repo): add contributor orientation guides #652

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 10 additions & 15 deletions .claude/commands/push.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,15 @@ name: push
description: Run pre-push checks including typecheck and tests
---

Run the following pre-push checks to ensure code quality before pushing to remote:
Run pre-push checks before pushing to remote:

1. **Type checking**: Run `yarn typecheck` to check for TypeScript errors
2. if you find any errors. fix them.
3. comment this lines in "dev" file:
```
run("node scripts/cleanup-desktop.js")
run("./scripts/cleanup-frontend.sh")
```
4. **Tests**: Run `./dev build-desktop && yarn web:prod` to ensure the apps build properly and tests pass
5. uncomment the lines in the "dev" file.
6. if there are any changes you made to fix the typecheck, commit with `--amend` the changes keeping the same message code. no need to change the commit message, just add the new changed files.
7. git pull
8. git push
9. **Report results**: Provide a summary of which checks passed or failed
1. **Type checking**: run `pnpm typecheck` from the repo root.
2. **Tests**: run `pnpm test` from the repo root.
3. **Build smoke checks**: run `./dev build-desktop` and `pnpm web:prod` when the changed files can affect desktop or
web builds.
4. **Formatting**: run `pnpm format:write` if the checks or edits touched formatted files.
5. If a check fails, fix it in place and rerun the failed command.
6. Report which checks passed or failed and include any remaining errors.

If any checks fails and you cannot fix it, describe that in the report, provide details about the errors so they can be fixed before pushing.
Do not edit `dev` just to run these checks. Do not amend, pull, or push unless the user explicitly asked for git
changes.
17 changes: 11 additions & 6 deletions .cursor/rules/web.mdc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,19 @@
---
description:
globs:
description:
globs:
alwaysApply: true
---
This mostly includes details about `frontend/apps/web`

This mostly includes details about `frontend/apps/web`.

# Tests

Run tests for things in the `frontend/apps/web`, if there is a test file present. Do this automatically without me asking you!
Run tests for things in `frontend/apps/web` automatically when there is a relevant test file.

Use pnpm from the repo root:

Run the tests by running `yarn web:test run <testFileName>` in the repo root. If you forget to include `run`, you will be stuck in watch mode! Orjust `yarn web:test run` to run all web test. Also you can run `yarn workspace @shm/shared test run` for tests in `frontend/packages/shared`
- `pnpm --filter @shm/web test -- <testFileName>` for one web test file.
- `pnpm web:test` for all web tests.
- `pnpm --filter @shm/shared test -- <testFileName>` for relevant shared package tests.

If you are working on something that is easily tested, you can offer to create a test
If you are working on something that is easily tested, offer to create or update a test.
2 changes: 2 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,8 @@

## Workflow

- For cross-subsystem work, read `docs/README.md`, `docs/code-map.md`, and the relevant glossary or architecture doc
before planning or making changes.
- Ask clarifying questions when ambiguity matters.
- Use OS temp dir for scratch files. Clean up after you're done.
- Ask for elevated permissions instead of working around sandboxing issues (if you can run in a sandbox).
Expand Down
81 changes: 41 additions & 40 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,13 @@
# Seed

Seed is a decentralized knowledge collaboration application for open
communities powered by a knowledge graph.
Seed is a decentralized knowledge collaboration application for open communities powered by a knowledge graph.

You can read more about the product and why we are here on our website: https://seed.hyper.media.

### Hypermedia Protocol

Seed Hypermedia is powered by the new [Hypermedia Web Protocol](https://hyper.media). This
open protocol provides secure identities, version control, semantic documents, multimedia,
and groups/organizations.
Seed Hypermedia is powered by the new [Hypermedia Web Protocol](https://hyper.media). This open protocol provides secure
identities, version control, semantic documents, multimedia, and groups/organizations.

### Desktop App + Web Server

Expand All @@ -20,32 +18,39 @@ This repo includes:

## ⚠️ Stability

This is software is being actively developed, and may contain bugs and rough edges.
We appreciate any feedback and bug reports, so if you find any, please open an issue.
This is software is being actively developed, and may contain bugs and rough edges. We appreciate any feedback and bug
reports, so if you find any, please open an issue.

The permanent data format has been declared stable, and we don't expect any breaking changes there.
Documentation is still missing though, but it will come.
The permanent data format has been declared stable, and we don't expect any breaking changes there. Documentation is
still missing though, but it will come.

We still recommend you to have a copy of anything valuable you put into the app, while we are polishing it,
and improving the overall stability.
We still recommend you to have a copy of anything valuable you put into the app, while we are polishing it, and
improving the overall stability.

## Dev Environment

See the [developer setup](./docs/docs/dev-setup.md) page for detailed instructions.
See the [developer setup](./docs/dev-setup.md) page for detailed instructions.

The dev environment on macOS+Linux uses the [Mise](https://mise.jdx.dev),
and [Direnv](https://direnv.net).
## Contributor orientation

The bare minimum required for compilation is to have Go, and NodeJS toolchains
installed.
Start with the [Seed Builder Guide](./docs/README.md) when building or fixing across subsystems. Useful entry points:

- [Domain glossary](./docs/domain/glossary.md) for account/key/vault/document/resource terminology.
- [Architecture overview](./docs/architecture/overview.md) for runtime boundaries and sources of truth.
- [Code map](./docs/code-map.md) for "if touching X, start here" file lists.
- [Frontend map](./frontend/README.md) and [backend map](./backend/README.md) for subsystem-specific orientation.

The dev environment on macOS+Linux uses the [Mise](https://mise.jdx.dev), and [Direnv](https://direnv.net).

The bare minimum required for compilation is to have Go, and NodeJS toolchains installed.

[./dev](./dev) is the main dev CLI. Run `./dev` to list commands, including:

- `./dev run-desktop`
- `./dev run-desktop-mainnet`
- `./dev build-desktop`
- `./dev run-site`
- `./dev build-site`
- `./dev run-web`
- `./dev build-web`

To run the dev build with the production network, use the following command:

Expand All @@ -58,22 +63,20 @@ SEED_P2P_TESTNET_NAME="" ./dev run-desktop
```bash
pnpm test # test all the packages
pnpm desktop:test # test desktop app (e2e only now)
pnpm site:test # test only site code (WIP)
pnpm web:test # test only web app code
```

## Web Build

## Group sites

Group sites need two programs to run. The daemon which includes the P2P node (go app)
and the frontend that renders documents (nextjs app). However for a production
deployment everything is orchestrated by docker compose. Read next sections for how to
either deploy a site on a production server or run it locally in dev mode
Group sites need two programs to run. The daemon which includes the P2P node (go app) and the frontend that renders
documents (Remix app). However for a production deployment everything is orchestrated by docker compose. Read next
sections for how to either deploy a site on a production server or run it locally in dev mode

### Deploy a Group Site

To deploy a group into a site, make sure you have a domain name and
a server with the following requirements:
To deploy a group into a site, make sure you have a domain name and a server with the following requirements:

1. At least 2GB RAM
2. Al least 512MB free space in root partition.
Expand All @@ -85,35 +88,33 @@ After checking that, run the following command in the server:
sh <(curl -sL https://raw.githubusercontent.com/seed-hypermedia/seed/main/website_deployment.sh) https://example.com
```

replacing `https://example.com` by your <`address`> If everything went well,
after some seconds, you should be watching a final output line like
`https://example.com/secret-invite/XXXX`. You should paste that link back into
the owner's application to register the newly created site and start publihing.
The site deployment workspace will default to `~/.seed-site`.
replacing `https://example.com` by your <`address`> If everything went well, after some seconds, you should be watching
a final output line like `https://example.com/secret-invite/XXXX`. You should paste that link back into the owner's
application to register the newly created site and start publishing. The site deployment workspace will default to
`~/.seed-site`.

#### Auto-Update a Site

If you want the site to auto update to latest stable images when they are pushed,
just execute the installation command with the `--auto-update` flag. Ex:
If you want the site to auto update to latest stable images when they are pushed, just execute the installation command
with the `--auto-update` flag. Ex:

```shell
sh <(curl -sL https://raw.githubusercontent.com/seed-hypermedia/seed/main/website_deployment.sh) https://example.com --auto-update
```

#### Replace Site

If you want to replace an old site with a new site in a different domain in the same machine,
you need to redeploy the site from scratch. Note that old content will be available as long as
the owner of the site is synced with the site at the moment of the replacement. On the server:
If you want to replace an old site with a new site in a different domain in the same machine, you need to redeploy the
site from scratch. Note that old content will be available as long as the owner of the site is synced with the site at
the moment of the replacement. On the server:

```shell
docker stop seed-web
mv ~/.seed-site ~/.seed-site.bak
docker start seed-web
```

Get the new secret link from the command line after starting the `seed-web` container
Now in the Seed App, the Owner of the site can go to the group he/she wants to (re)deploy
and click on the three dots, and publish group to site. Enter the new secret and the old content
should be now available in the new site. If there is no new content (A completely new group), then
the site will be empty ready to accept documents
Get the new secret link from the command line after starting the `seed-web` container Now in the Seed App, the Owner of
the site can go to the group he/she wants to (re)deploy and click on the three dots, and publish group to site. Enter
the new secret and the old content should be now available in the new site. If there is no new content (A completely new
group), then the site will be empty ready to accept documents
47 changes: 47 additions & 0 deletions backend/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Backend

Status: current.

The backend is the Go runtime for Seed. It contains the daemon, API implementations, blob formats/indexing, SQLite
storage, P2P networking, and backend tests.

## Package map

| Path | Ownership |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| [`api`](./api) | gRPC service implementations and API test helpers. Mirrors `proto/**` service areas. |
| [`api/documents/v3alpha`](./api/documents/v3alpha) | Documents, resources, comments, contacts, access control, document history. |
| [`api/entities/v1alpha`](./api/entities/v1alpha) | Entity timeline, search, delete/undelete, discovery entry points. |
| [`api/activity/v1alpha`](./api/activity/v1alpha) | Activity feed and subscription APIs. |
| [`api/daemon/v1alpha`](./api/daemon/v1alpha) | Daemon admin/key/vault/domain APIs. |
| [`blob`](./blob) | Signed blob formats (`Change`, `Ref`, `Comment`, `Capability`, profile/contact), blob store/indexing, visibility propagation. |
| [`storage`](./storage) | SQLite store, schema source of truth, migrations, local vault storage. Read [`storage/AGENTS.md`](./storage/AGENTS.md) before editing. |
| [`hmnet`](./hmnet) | libp2p node, Bitswap/file serving, peer/debug endpoints, P2P client/server plumbing. |
| [`hmnet/syncing`](./hmnet/syncing) | Authorized sync, discovery, scheduling, sync server. |
| [`daemon`](./daemon) | App composition: storage, index, network, sync, gRPC, HTTP, metrics, reindexing, LLM embedding. |
| [`cmd/seed-daemon`](./cmd/seed-daemon) | CLI entry point for the daemon binary. |
| [`core`](./core) | Cryptography, principals, key pairs, keystores, mnemonics. |
| [`config`](./config) | Daemon configuration and defaults. |
| [`llm`](./llm) | Embedding backends and llama.cpp/Ollama integration. |
| [`util`](./util) | Shared Go utilities; keep new helpers small and justified. |

## Sources of truth

- Proto contracts: [`../proto`](../proto).
- DB schema: [`storage/schema.sql`](./storage/schema.sql).
- DB migrations: [`storage/storage_migrations.go`](./storage/storage_migrations.go).
- Blob formats: [`blob/blob_*.go`](./blob).
- Daemon composition: [`daemon/daemon.go`](./daemon/daemon.go).

## Common commands

```bash
go test ./backend/...
golangci-lint run --new-from-merge-base origin/main ./backend/...
go install ./backend/... # compile-only check
./dev run-backend -- -http.port=53001 -grpc.port=53002 -p2p.port=53000
./dev gen //backend/... # after generated schema/proto-affecting changes
```

For local CI parity before pushing, use the backend workflows from
[`../docs/local-ci-with-agent-ci.md`](../docs/local-ci-with-agent-ci.md).
Loading
Loading