docs: add AGENTS.md and architecture diagrams

AGENTS.md

@@ -0,0 +1,88 @@
+# Agent Instructions - Branch Protection Workflow
+
+## ⚠️ IMPORTANT: This repository has branch protection enabled
+
+Direct pushes to `main`/`master` are **BLOCKED**. All changes must go through Pull Requests.
+
+## Required Workflow
+
+### Making Changes
+
+1. **Create a feature branch** (never work on main/master):
+   ```bash
+   git checkout -b feat/your-feature-name
+   # or
+   git checkout -b fix/issue-description
+   ```
+
+2. **Make your changes and commit**:
+   ```bash
+   git add .
+   git commit -m "feat: descriptive commit message"
+   ```
+
+3. **Push the branch**:
+   ```bash
+   git push origin feat/your-feature-name
+   ```
+
+4. **Create a Pull Request** using the GitHub CLI:
+   ```bash
+   gh pr create --title "feat: Add new feature" --body "Description of changes"
+   ```
+
+5. **Merge after review**:
+   ```bash
+   gh pr merge --squash --delete-branch
+   ```
+
+### Branch Naming Conventions
+
+- `feat/` - New features
+- `fix/` - Bug fixes
+- `docs/` - Documentation changes
+- `refactor/` - Code refactoring
+- `test/` - Test additions/changes
+- `chore/` - Maintenance tasks
+
+### What You MUST NOT Do
+
+- ❌ Never push directly to `main` or `master`
+- ❌ Never use `git push --force` on protected branches
+- ❌ Never delete the `main` or `master` branch
+- ❌ Never commit directly without a PR
+
+### Git Configuration
+
+When working with this repository, ensure your git config includes:
+```bash
+git config user.name "Your Name"
+git config user.email "your.email@example.com"
+```
+
+## Security Considerations
+
+- All changes go through PR review
+- No force pushes allowed
+- Branch deletion is prevented
+- CI checks should pass before merge
+
+## Quick Reference
+
+```bash
+# Start new work
+git checkout -b feat/new-feature
+
+# After making changes
+git add . && git commit -m "feat: add new feature"
+git push origin feat/new-feature
+
+# Create PR
+gh pr create --title "feat: Add new feature" --body "What it does"
+
+# After PR approved
+gh pr merge --squash --delete-branch
+
+# Back to main
+git checkout main && git pull
+```

docs/architecture/diagrams/classes.mmd

@@ -0,0 +1,124 @@
+```mermaid
+classDiagram
+    %% Base Entities
+    class User {
+        +String id
+        +String email
+        +String name
+        +UserRole role
+        +DateTime createdAt
+        +create() User
+        +validate() boolean
+    }
+
+    class Organization {
+        +String id
+        +String name
+        +List~User~ members
+        +Settings settings
+        +create() Organization
+    }
+
+    %% Enums
+    class UserRole {
+        <<enumeration>>
+        ADMIN
+        MEMBER
+        VIEWER
+    }
+
+    %% Services
+    class AuthService {
+        +login(credentials) Token
+        +register(user) User
+        +validateToken(token) User
+    }
+
+    class DeploymentService {
+        +deploy(project, env) Deployment
+        +rollback(deploymentId) void
+        +getStatus(deploymentId) DeploymentStatus
+    }
+
+    class EnvironmentRegistry {
+        +List~Environment~ environments
+        +addEnvironment(env) void
+        +updateEnvironment(env) void
+        +getEnvironment(name) Environment
+    }
+
+    %% Data Models
+    class Environment {
+        +String name
+        +String url
+        +DatabaseConfig database
+        +TechStack techStack
+        +DeploymentInfo deployment
+    }
+
+    class DatabaseConfig {
+        +String type
+        +String host
+        +int port
+        +String name
+    }
+
+    class TechStack {
+        +String frontend
+        +String backend
+        +String database
+        +String deployment
+    }
+
+    class Deployment {
+        +String id
+        +String project
+        +String environment
+        +String status
+        +DateTime deployedAt
+        +String commitHash
+    }
+
+    %% Relationships
+    User "1" --> "*" Organization : belongs to
+    Organization "1" --> "*" Environment : manages
+
+    AuthService --> User : authenticates
+    DeploymentService --> Deployment : creates
+    EnvironmentRegistry --> Environment : tracks
+
+    User <|-- UserRole
+    Environment --> DatabaseConfig : uses
+    Environment --> TechStack : uses
+    Environment --> Deployment : has
+```
+
+### Documentation Standards for Types
+
+Every important type should be documented with:
+
+1. **Purpose** - What the type represents
+2. **Properties** - All fields with types and meanings
+3. **Relationships** - How it connects to other types
+4. **Usage** - Where it's used in the system
+
+Example:
+
+```typescript
+/**
+ * Represents a deployment environment.
+ * 
+ * @property name - Environment identifier (e.g., "production", "staging")
+ * @property url - Base URL for the deployed application
+ * @property database - Database connection configuration
+ * @property techStack - Technology stack used (frontend, backend, database)
+ * @property deployment - Deployment details (platform, status, commit)
+ */
+interface Environment {
+  name: string;
+  url: string;
+  database: DatabaseConfig;
+  techStack: TechStack;
+  deployment: DeploymentInfo;
+}
+```

docs/architecture/diagrams/container.mmd

@@ -0,0 +1,83 @@
+```mermaid
+C4Container
+title Container Diagram for Sensible Analytics Platform
+
+Person(admin, "Administrator", "Manages settings and configurations")
+Person(user, "User", "Uses analytics applications")
+
+Container_Boundary(mobile, "Mobile Applications") {
+    Container(mobile_app, "CardScannerApp", "React Native", "Scans business cards")
+}
+
+Container_Boundary(web_frontend, "Web Frontends") {
+    Container(prop_roo_frontend, "PropRoo Frontend", "React + Vite", "Property analytics UI")
+    Container(folio_frontend, "Folio Frontend", "React", "Portfolio tracking UI")
+    Container(qullamaggie_frontend, "Qullamaggie Frontend", "React", "Stock screening UI")
+    Container(rentroo_frontend, "Rentroo Frontend", "React", "Property management UI")
+    Container(crewcircle_frontend, "Crewcircle Frontend", "React", "Workforce management UI")
+    Container(video_frontend, "Video Analysis Frontend", "React", "Educational video UI")
+}
+
+Container_Boundary(api_layer, "API Layer") {
+    Container(prop_roo_api, "PropRoo API", "FastAPI", "Property analytics backend")
+    Container(folio_api, "Folio API", "Rust/Tauri", "Portfolio tracking backend")
+    Container(qullamaggie_api, "Qullamaggie API", "Python", "Stock screening backend")
+    Container(rentroo_api, "Rentroo API", "Node.js", "Property management backend")
+    Container(crewcircle_api, "Crewcircle API", "Node.js", "Workforce management backend")
+    Container(video_api, "Video Analysis API", "Python", "Video processing backend")
+}
+
+Container_Boundary(ai_services, "AI Services") {
+    Container(llm_service, "LLM Service", "OpenAI", "Language model processing")
+    Container(ocr_service, "OCR Service", "OpenAI Vision", "Business card scanning")
+    Container(transcription_service, "Transcription Service", "OpenAI Whisper", "Video transcription")
+}
+
+Container_Boundary(data_layer, "Data Layer") {
+    ContainerDb(prop_roo_db, "PropRoo DB", "DuckDB/Parquet", "Property data storage")
+    ContainerDb(folio_db, "Folio DB", "SQLite", "Portfolio data storage")
+    ContainerDb(rentroo_db, "Rentroo DB", "PostgreSQL", "Property management data")
+    ContainerDb(crewcircle_db, "Crewcircle DB", "PostgreSQL", "Workforce data")
+    ContainerDb(neon_main, "Main Neon DB", "PostgreSQL", "Shared data storage")
+}
+
+System_Ext(vercel, "Vercel", "Deployment platform")
+System_Ext(cloudflare, "Cloudflare", "CDN and WAF")
+System_Ext(gcp, "Google Cloud Platform", "Compute and storage")
+System_Ext(oracle, "Oracle Cloud", "Infrastructure")
+System_Ext(yahoo_finance, "Yahoo Finance", "Stock data")
+System_Ext(email_provider, "Email Provider", "SendGrid/Resend", "Email notifications")
+
+Rel(user, prop_roo_frontend, "Uses")
+Rel(user, folio_frontend, "Uses")
+Rel(user, qullamaggie_frontend, "Uses")
+Rel(user, rentroo_frontend, "Uses")
+Rel(user, crewcircle_frontend, "Uses")
+Rel(user, mobile_app, "Uses")
+
+Rel(prop_roo_frontend, prop_roo_api, "Calls")
+Rel(folio_frontend, folio_api, "Calls")
+Rel(qullamaggie_frontend, qullamaggie_api, "Calls")
+Rel(rentroo_frontend, rentroo_api, "Calls")
+Rel(crewcircle_frontend, crewcircle_api, "Calls")
+Rel(mobile_app, card_scanner, "Uses")
+
+Rel(prop_roo_api, prop_roo_db, "Reads/Writes")
+Rel(folio_api, folio_db, "Reads/Writes")
+Rel(rentroo_api, rentroo_db, "Reads/Writes")
+Rel(crewcircle_api, crewcircle_db, "Reads/Writes")
+
+Rel(prop_roo_api, vercel, "Hosted on")
+Rel(qullamaggie_api, vercel, "Hosted on")
+Rel(crewcircle_api, vercel, "Hosted on")
+Rel(rentroo_api, oracle, "Hosted on")
+PropRoo_API --> cloudflare
+Rel(prop_roo_api, neon_main, "Uses")
+
+Rel(qullamaggie_api, yahoo_finance, "Fetches stock data")
+Rel(qullamaggie_api, llm_service, "Uses")
+
+Rel(card_scanner, ocr_service, "Uses")
+Rel(video_api, transcription_service, "Uses")
+Rel(video_api, llm_service, "Uses")
+```