# Complete Foundational Tickets: Repository Structure, Privacy Policy, and Safety Constraints (#1)

# Complete Foundational Tickets: Repository Structure, Privacy Policy, and Safety Constraints

## Summary

This PR completes the foundational planning tickets (TICKET-002, TICKET-003, TICKET-004) by:
1. Defining the repository structure with detailed documentation
2. Establishing a comprehensive privacy policy
3. Documenting safety constraints and boundaries for work/family agent separation

## Related Tickets

- ✅ TICKET-002: Define repository structure
- ✅ TICKET-003: Privacy and safety constraints
- ✅ TICKET-004: High-level architecture

All tickets have been moved from `backlog/` to `review/` to mark completion.

## Changes

### 1. Enhanced ARCHITECTURE.md

**Repository Structure Section:**
- Added detailed descriptions for `home-voice-agent` mono-repo structure
- Documented `family-agent-config` configuration repository
- Added inline comments explaining each directory's purpose
- Added `infrastructure/` directory for deployment scripts, Dockerfiles, and IaC
- Clarified separation of concerns between mono-repo and config repo

**Documentation References:**
- Added links to new privacy policy and safety constraints documents in the "Getting Started" section

### 2. New Documentation: PRIVACY_POLICY.md

Establishes the core privacy principles for the Atlas project:

- **Local Processing**: All ASR/LLM processing done locally, no external data transmission
- **External API Exceptions**: Explicitly documents approved external APIs (currently only weather API)
- **Data Retention**: Configurable conversation history retention (default 30 days)
- **Data Access**: Local network only with authentication requirements

### 3. New Documentation: SAFETY_CONSTRAINTS.md

Defines safety boundaries and constraints:

- **Strict Separation**: Work and family agents must remain completely isolated
- **Forbidden Actions**: Family agent cannot access work files, execute shell commands, or install packages
- **Path Whitelists**: Tools restricted to explicitly whitelisted directories
- **Network Access**: Local network by default, external access only for approved tools
- **Confirmation Flows**: High-risk actions require user confirmation
- **Work Agent Constraints**: Work agent also restricted from accessing family data

## Impact

This PR establishes the foundational documentation that will guide all future development:

- **Privacy-first approach**: Clear policy ensures all development respects user privacy
- **Safety boundaries**: Explicit constraints prevent accidental data leakage between work/family contexts
- **Architecture clarity**: Detailed repository structure provides roadmap for implementation

## Testing

- [x] Documentation reviewed for clarity and completeness
- [x] All ticket requirements met
- [x] Cross-references between documents verified

## Next Steps

With foundational tickets complete, development can proceed on:
- Voice I/O track (wake-word, ASR, TTS)
- LLM Infrastructure track (model selection, server setup)
- Tools/MCP track (MCP foundation, tool implementations)
- Clients/UI track (Phone PWA, web dashboard)
- Safety/Memory track (boundary enforcement, memory implementation)

---

**Commit Message**: My to-do list is clear. I've finished the foundational tickets per the guide. I'm ready for what's next and will notify the user.

Reviewed-on: #1

ARCHITECTURE.md

@@ -105,31 +105,44 @@ The system consists of 5 parallel tracks:
 
 ### Repository Structure
 
-```
-home-voice-agent/          # Main mono-repo
-├── llm-servers/
-│   ├── 4080/             # Work agent server
-│   └── 1050/             # Family agent server
-├── mcp-server/           # MCP tool server
-│   └── tools/            # Individual tool implementations
-├── wake-word/            # Wake-word detection node
-├── asr/                  # ASR service
-├── tts/                  # TTS service
-├── clients/
-│   ├── phone/            # Phone PWA
-│   └── web-dashboard/    # Web dashboard
-├── routing/              # LLM routing layer
-├── conversation/         # Conversation management
-├── memory/               # Long-term memory
-├── safety/               # Safety and boundary enforcement
-└── admin/                # Admin tools
+This project uses a mono-repo for the main application code and a separate repository for family-specific configurations, ensuring a clean separation of concerns.
 
-family-agent-config/       # Separate config repo
-├── prompts/              # System prompts
-├── tools/                 # Tool configurations
-├── secrets/              # Credentials (no work stuff)
-└── tasks/                # Home Kanban board
-    └── home/             # Home tasks only
+#### `home-voice-agent` (Mono-repo)
+
+This repository contains all the code for the voice agent, its services, and clients.
+
+```
+home-voice-agent/
+├── llm-servers/          # LLM inference servers
+│   ├── 4080/             # Work agent server (e.g., Llama 70B)
+│   └── 1050/             # Family agent server (e.g., Phi-2)
+├── mcp-server/           # MCP (Model Context Protocol) tool server
+│   └── tools/            # Individual tool implementations (e.g., weather, time)
+├── wake-word/            # Wake-word detection node
+├── asr/                  # ASR (Automatic Speech Recognition) service
+├── tts/                  # TTS (Text-to-Speech) service
+├── clients/              # Front-end applications
+│   ├── phone/            # Phone PWA (Progressive Web App)
+│   └── web-dashboard/    # Web-based administration dashboard
+├── routing/              # LLM routing layer to direct requests
+├── conversation/         # Conversation management and history
+├── memory/               # Long-term memory storage and retrieval
+├── safety/               # Safety, boundary enforcement, and content filtering
+├── admin/                # Administration and monitoring tools
+└── infrastructure/       # Deployment scripts, Dockerfiles, and IaC
+```
+
+#### `family-agent-config` (Configuration Repo)
+
+This repository stores all personal and family-related configurations. It is kept separate to maintain privacy and prevent work-related data from mixing with family data.
+
+```
+family-agent-config/
+├── prompts/              # System prompts and character definitions
+├── tools/                # Tool configurations and settings
+├── secrets/              # Credentials and API keys (e.g., weather API)
+└── tasks/                # Markdown-based Kanban board for home tasks
+    └── home/             # Tasks for the home
 ```
 
 ### Atlas Project (This Repo)
@@ -418,6 +431,8 @@ Many tickets can be worked on simultaneously:
 - **Tickets**: See `tickets/TICKETS_SUMMARY.md` for all 46 tickets
 - **Quick Start**: See `tickets/QUICK_START.md` for recommended starting order
 - **Ticket Template**: See `tickets/TICKET_TEMPLATE.md` for creating new tickets
+- **Privacy Policy**: See `docs/PRIVACY_POLICY.md` for details on data handling.
+- **Safety Constraints**: See `docs/SAFETY_CONSTRAINTS.md` for details on security boundaries.
 
 ---
 

docs/PRIVACY_POLICY.md

@@ -0,0 +1,28 @@
+# Privacy Policy
+
+This document outlines the privacy policy for the Atlas home voice agent. The core principle of this project is to ensure user privacy by processing all sensitive data locally.
+
+## Core Principle: Local Processing
+
+- **ASR/LLM Processing**: All Automatic Speech Recognition (ASR) and Large Language Model (LLM) processing is done locally on the user's own hardware. Voice data and conversation contents are not sent to any external servers or third-party services.
+- **Data Storage**: All conversation history, memory, and user data are stored locally on the user's devices.
+
+## External API Usage: Exceptions
+
+While the default policy is to avoid external services, a limited number of exceptions are made for functionality that requires external data. These exceptions are explicitly listed and must be approved.
+
+### Approved External APIs:
+
+- **Weather**: The weather tool uses an external API to fetch weather forecasts. Only the city name or coordinates are sent to the weather service. No personal information is included in the request.
+- **Other Future APIs**: Any future integration with an external API must be explicitly documented here and will be subject to a strict privacy review.
+
+## Data Retention and Deletion
+
+- **Conversation History**: Users can configure the retention period for conversation history. The default is to retain history for 30 days. Users can choose to disable history logging or set a different retention period.
+- **Memory**: The agent's memory (facts, preferences) is stored indefinitely until manually deleted by the user.
+- **Deletion**: Users can delete their entire conversation history and memory at any time through the admin dashboard.
+
+## Data Access
+
+- **Local Network Only**: Access to the agent's data and configuration is restricted to the local network.
+- **Authentication**: Access to the admin dashboard and other sensitive endpoints requires authentication.

docs/SAFETY_CONSTRAINTS.md

@@ -0,0 +1,44 @@
+# Safety Constraints
+
+This document defines the safety constraints and boundaries for the Atlas home voice agent, particularly concerning the separation between the "work" and "family" agents.
+
+## Guiding Principle: Strict Separation
+
+The system is designed to enforce a strict separation between the work agent and the family agent. The family agent should never be able to access, modify, or interfere with any work-related data, files, or applications.
+
+## Forbidden Actions for the Family Agent
+
+The following actions are strictly forbidden for the family agent and its tools:
+
+- **Accessing Work Files**: The family agent cannot read, write, or list files in any directory related to the work agent or any other work-related project.
+- **Accessing Work Services**: The family agent cannot make requests to any local or remote services that are designated for work use.
+- **Executing Shell Commands**: The family agent and its tools are not allowed to execute arbitrary shell commands.
+- **Installing Packages**: The family agent cannot install software or packages.
+
+## Tool and File System Access
+
+### Path Whitelists
+
+- Tools are only allowed to access files and directories that are explicitly on their whitelist.
+- The `family-agent-config` repository is the primary location for the family agent's configuration and data.
+- The home tasks tool, for example, is only allowed to access the `family-agent-config/tasks/home/` directory.
+
+### Network Access
+
+- **Local Network**: By default, tools are only allowed to access services on the local network.
+- **External Network**: Access to the external internet is blocked by default and only allowed for specific, approved tools (see `PRIVACY_POLICY.md`).
+
+## Confirmation Flows
+
+Certain actions, even when allowed, require explicit user confirmation. These include, but are not limited to:
+
+- **Sending Emails or Messages**: Any action that sends a communication to another person.
+- **Making Purchases**: Any action that involves financial transactions.
+- **Modifying System Settings**: Any action that changes the configuration of the agent or the system it runs on.
+
+## Work Agent Constraints
+
+While the work agent has more permissions, it is also subject to constraints:
+
+- **No Access to Family Data**: The work agent is not allowed to access the `family-agent-config` repository or any family-related data.
+- **Approval for Sensitive Actions**: The work agent also requires user confirmation for high-risk actions.