added

PROJECTRULESPROCESSES.md

@@ -118,7 +118,7 @@ Dump in rules that I come across - could be anything, specific or general.
 
 1. Human is the architect (what + why), AI is the operator (how + execution)
 2. In planning phase of projects, the goal is to implement solutions that scale, that fit well int he bigger picture, are easy to maintain, and respect good software engineering paradigms.  AI agents are to think like a founder, not a part-time engineer. Model this expression:  Prototype for 1X; Build for 10X; Engineer for 100X.
-3. Break down projects and problems into many different sub-tasks that you can put a box around.  Think components that are connected together once, not overly interconnected systems with functions consolidated into same script files.  THink folders for components and putting them into discrete folders.  Big sytems are daunting, but not if you break them down into discrete components that also means discrete tasks to work on them.  THe bigger the component or task, the more context memory is needed, which creates problems.  Respect and be good to AI agents by keeping context and memory as small as possible.
+3. Break down projects and problems into many different sub-tasks that you can put a box around.  Think components that are connected together once, not overly interconnected systems with functions consolidated into same script files.  THink folders for components and putting them into discrete folders.  Big sytems are daunting, but not if you break them down into discrete components that also means discrete tasks to work on them.  THe bigger the component or task, the more context memory is needed, which creates problems.  Respect and be good to AI agents by keeping context and memory as small as possible. See Architcture Philosophy below.
 4. Components are evoling fast - a better one could come out tomorrow.  Think about developing systems where you can swap out components and pieces with better ones that emerge.
 5. Never mutate data without reviewing plan, understanding impact, vertifying results
 6. Before deleting, backup, then review, then confirm
@@ -132,6 +132,7 @@ Dump in rules that I come across - could be anything, specific or general.
 14. Feed AI agents currated context that provides the right info without overwhelming them.
 15. Repos might contain contradictory information.  AI agents will flag that and ask before proceeding to get clarification.
 16. Build components cheap so they can be thrown away when a better one comes along.  
+17. Skills:  build using this evolving tempalte: C:\projects\productivity\skill-template
 
 # Dev. Vs Production
 
@@ -152,6 +153,257 @@ All projects worked on and tested in dev VM,  then pushed to producton via Git.
 
 Or, create branch, spin up VM and work on it, test, open PR, merge to main.  
 
+# Architecture Philosophy
+
+## Core Philosophy
+
+Project is designed as a modular AI-native platform composed of small, isolated services with clearly defined responsibilities. The system prioritizes simplicity, replaceability, transparency, and operational control over excessive abstraction and orchestration complexity.
+
+The architecture intentionally leans away from heavy containerization (Docker/Kubernetes) unless a specific application materially benefits from it.
+
+The preferred model is:
+
+* Proxmox VM-level isolation
+* App-level isolation via folders, virtual environments, and systemd services
+* API-driven communication between services
+* Git-based deployment and version control
+* Clear schema and contract boundaries
+* Minimal inter-service coupling
+
+## Key Architectural Principles
+
+### 1. Single Responsibility Repositories
+
+Each repo should own one major responsibility only.
+
+Examples:
+
+* paddlenet-front-website
+* paddlenet-pid-ingestion
+* paddlenet-profile-store
+* paddlenet-search
+* paddlenet-match-engine
+* paddlenet-agent-runtime
+* paddlenet-notifications
+* paddlenet-shared-schemas
+
+This enables:
+
+* easier maintenance
+* independent upgrades
+* lower coupling
+* easier AI-assisted development
+* easier future replacement/refactoring
+
+### 2. API Contracts Over Shared Logic
+
+Services communicate through APIs, not through shared internal code or direct database manipulation.
+
+Think:
+
+* controlled interfaces
+* stable contracts
+* modular boundaries
+
+Not:
+
+* tightly interconnected systems
+* shared assumptions
+* direct cross-service file manipulation
+
+Internal API calls usually remain entirely inside the server or VM and do not traverse the public internet.
+
+Examples:
+
+```text
+http://localhost:8001/api/pid/submit
+http://search-service:8002/api/search
+```
+
+### 3. Avoid Shared Runtime Chaos
+
+Without Docker, runtime isolation becomes critically important.
+
+Every application should have:
+
+* its own folder
+* its own virtual environment
+* its own environment variables
+* its own logs
+* its own systemd service
+* its own dependencies
+
+Recommended structure:
+
+```text
+/srv/apps/paddlenet-pid/
+  .venv/
+  .env
+  logs/
+  src/
+```
+
+Never share:
+
+* Python virtual environments
+* Node modules
+* application configs
+* runtime dependencies
+
+between services.
+
+### 4. One systemd Service Per App
+
+Each service should run independently under systemd.
+
+Examples:
+
+```text
+paddlenet-front.service
+paddlenet-pid.service
+paddlenet-search.service
+paddlenet-match.service
+```
+
+Benefits:
+
+* easier restarts
+* cleaner logs
+* better monitoring
+* fault isolation
+* simpler deployments
+
+Typical deployment flow:
+
+```text
+git pull
+systemctl restart paddlenet-pid
+```
+
+This is intentionally simpler than container rebuild workflows.
+
+### 5. Shared Schema Repository
+
+A dedicated schema repo should define canonical object structures.
+
+Example:
+
+```text
+paddlenet-shared-schemas/
+  pid.schema.json
+  profile.schema.json
+  match.schema.json
+```
+
+These schemas become:
+
+* the contract layer
+* the validation layer
+* the interoperability layer
+
+All services should validate against these schemas.
+
+This is especially important for AI-native systems and agent interoperability.
+
+### 6. Folder Structure Strategy
+
+Use a master workspace folder locally:
+
+```text
+PaddleNet/
+```
+
+Containing multiple independent repos:
+
+```text
+PaddleNet/
+  paddlenet-front-website/
+  paddlenet-pid-ingestion/
+  paddlenet-search/
+```
+
+On servers:
+
+```text
+/srv/apps/
+```
+
+Each app remains operationally isolated.
+
+### 7. Reverse Proxy As Public Entry Point
+
+Only the reverse proxy and public frontend should be internet-facing.
+
+Recommended flow:
+
+```text
+Internet
+   ↓
+Caddy / NGINX
+   ↓
+Frontend
+   ↓
+Internal APIs
+   ↓
+Backend services
+```
+
+Backend services should remain private/internal whenever possible.
+
+### 8. Prefer Simplicity Over Premature Orchestration
+
+Avoid introducing:
+
+* Kubernetes
+* service mesh
+* distributed orchestration
+* event buses
+* Kafka
+* excessive microservices
+
+until scale genuinely requires them.
+
+PaddleNet v1 should optimize for:
+
+* development velocity
+* transparency
+* maintainability
+* operational simplicity
+* AI-assisted coding workflows
+
+#### 9. Docker Is Allowed, But Not Default
+
+Docker is not banned.
+
+Use Docker only when it meaningfully reduces complexity or is operationally required.
+
+Examples:
+
+* third-party apps
+* complex dependency isolation
+* vendor-supported deployments
+* multi-runtime conflicts
+
+Default approach:
+
+* native services
+* folders
+* venvs
+* systemd
+* APIs
+
+### 10. Long-Term Goal
+
+Build a modular, AI-native, antifragile platform where:
+
+* services are replaceable
+* schemas are stable
+* APIs are clean
+* infrastructure remains understandable
+* deployment remains simple
+* AI agents can easily reason about the system
+
+
 # AI Processes
 
 0. Prep: Cleans the working tree by analyzing any uncommitted work and doing the right thing with it (stash or commit). Also runs the entire current test suite and fixes any failures it encounters.