p4n4-docs

ADR-001: Multi-Repository Architecture

Date: 2026 Status: Accepted Deciders: raisga core team

Context

p4n4 needs to support three distinct runtime stacks (IoT, GenAI, Edge AI) that can be deployed independently or together. A single monorepo would couple release cycles and make standalone deployment unnecessarily complex.

Decision

Split p4n4 into 8 repositories under the raisga GitHub organisation, each with a single well-defined responsibility:

Repo	Responsibility
`.github`	Org profile, shared workflows, issue templates
`p4n4`	Umbrella: architecture, ADRs, cross-cutting docs
`p4n4-iot`	IoT stack — owns `p4n4-net` Docker bridge
`p4n4-ai`	GenAI stack — attaches to `p4n4-net`
`p4n4-edge`	Edge Impulse stack — attaches to `p4n4-net`
`p4n4-cli`	Python CLI; published to PyPI as `p4n4`
`p4n4-templates`	Community template registry
`p4n4-docs`	Full technical reference; deployed as static site

Consequences

Positive:

Each stack can be versioned and released independently.
Teams can fork a single stack without pulling in unrelated services.
The CLI becomes the single integration layer, eliminating manual cross-stack wiring.

Negative:

Cross-stack secrets (e.g., INFLUXDB_ADMIN_TOKEN) must be kept consistent manually when stacks are used without the CLI.
PRs that touch multiple stacks require coordinated merges.

Alternatives considered

Monorepo with separate docker-compose files — simpler initially, but version tagging and PyPI publishing become awkward.
Helm charts — higher barrier to entry; ruled out for Phase 1 (self-hosted, non-k8s targets).

References

Architecture reference in p4n4-docs