# ARP - Agent Resource Platform

A GraphQL-based coordination system for users and agents to collaborate on services, tasks, and communications.

## Overview

ARP (Agent Resource Planner) is a coordination backend that enables human users and AI agents to work together on shared services. It provides:

- **User Management** - Role-based access control with fine-grained permissions
- **Service Coordination** - Create and manage services with multiple participants
- **Task Management** - Assignable work items with status tracking
- **Notes** - Attach notes to services for context
- **Messaging** - Real-time chat channels between participants

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      GraphQL API                            │
│  (gqlgen - schema-first, type-safe resolvers)               │
├─────────────────────────────────────────────────────────────┤
│                    Auth Middleware                          │
│  (JWT tokens, permission checks)                            │
├─────────────────────────────────────────────────────────────┤
│                     GORM Models                             │
│  User → Role → Permission                                   │
│  Service → Task → TaskStatus                                │
│  Channel → Message                                          │
│  Note                                                       │
├─────────────────────────────────────────────────────────────┤
│                   SQLite Database                           │
│  (arp.db - can be swapped for PostgreSQL/MySQL)             │
└─────────────────────────────────────────────────────────────┘
```

## Quick Start

### Prerequisites

- Go 1.21+
- SQLite3 (or modify for PostgreSQL/MySQL)

### Running the Server

```bash
# Clone and run
go run server.go

# Server starts on http://localhost:8080
```

### Running Tests

```bash
go test ./... -v
```

## API Interaction with Bash

### 1. Start the Server

```bash
go run server.go &
# Server runs on http://localhost:8080
```

### 2. Inspect the GraphQL Schema

Use GraphQL introspection to discover the API schema:

```bash
# Get all types in the schema
curl -s -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __schema { types { name kind description fields { name type { name kind ofType { name } } } } } }"}' | jq

# Get all queries and mutations
curl -s -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __schema { queryType { fields { name description } } mutationType { fields { name description } } } }"}' | jq
```

### 3. Initialize Database with Seed Data

Run the SQL bootstrap script to create permissions, roles, task statuses, and an admin user:

```bash
# Initialize the database with seed data
sqlite3 arp.db < init.sql

# Verify the data was created
sqlite3 arp.db "SELECT name FROM roles;"
# Output:
# admin
# manager
# user

sqlite3 arp.db "SELECT email FROM users;"
# Output:
# admin@example.com
```

The `init.sql` script creates:
- **36 permissions** covering all CRUD operations for each entity type
- **3 roles**: admin (full access), manager (service/task management), user (read-only + notes/messages)
- **1 admin user** with email `admin@example.com` and password `secret123`
- **6 task statuses**: open, in_progress, blocked, review, done, cancelled

### 4. Login and Get JWT Token

```bash
# Login to get JWT token
TOKEN=$(curl -s -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation { login(email: \"admin@example.com\", password: \"secret123\") { token user { email roles { name } } } }"}' | jq -r '.data.login.token')

echo "Token: $TOKEN"
```

### 5. Pull List of Services (Authenticated)

```bash
# Get all services with authentication
curl -s -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query":"{ services { id name description createdAt participants { email } tasks { title status { label } } } }"}' | jq
```

### 6. Create a Service

```bash
# Create a new service
curl -s -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query":"mutation { createService(input: {name: \"Project Alpha\", description: \"New project\", createdById: \"1\", participants: [\"1\"]}) { id name } }"}' | jq
```

### 7. Query Single Service by ID

```bash
# Get a specific service
curl -s -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query":"{ service(id: \"1\") { id name description createdBy { email } participants { email } tasks { id title priority status { code label } } } }"}' | jq
```

## Authentication & Authorization

### Permission System

The system uses a hierarchical permission model:

```
User ─┬─ has many ─→ Role ─┬─ has many ─→ Permission
      │                    │
      └─ e.g., "admin"     └─ e.g., "service:create"
```

### Required Permissions for Operations

| Operation | Required Permission |
|-----------|---------------------|
| Update User | `user:update` |
| Delete User | `user:delete` |
| Update Task | `task:update` |
| Delete Task | `task:delete` |
| Update Note | `note:update` |
| Delete Note | `note:delete` |
| Update Service | `service:update` |
| Delete Service | `service:delete` |
| ... | ... |

### Using Authentication in Requests

```bash
# Include JWT token in Authorization header
curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"query":"..."}'
```

## GraphQL Schema Overview

### Core Types

- **User** - Agent or human account
- **Role** - Groups of permissions
- **Permission** - Fine-grained access control (e.g., `task:create`)
- **Service** - Coordination unit with participants and tasks
- **Task** - Assignable work item with status
- **TaskStatus** - Workflow states (open, in_progress, done)
- **Note** - Notes attached to services
- **Channel** - Chat between participants
- **Message** - Individual chat messages

### Key Queries

```graphql
type Query {
  users: [User!]!
  user(id: ID!): User
  services: [Service!]!
  service(id: ID!): Service
  tasks: [Task!]!
  task(id: ID!): Task
  roles: [Role!]!
  permissions: [Permission!]!
  # ... more queries
}
```

### Key Mutations

```graphql
type Mutation {
  login(email: String!, password: String!): AuthPayload!
  createUser(input: NewUser!): User!
  createService(input: NewService!): Service!
  createTask(input: NewTask!): Task!
  # ... more mutations
}
```


## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `JWT_SECRET` | `your-secret-key-change-in-production` | Secret for JWT signing |


## Todo
@todo: all operations should only be allowed for logged in users
@todo: Change permissions such that users can
  * only update, delete the messages they sent
  * only update, delete notes they created
@todo: add a UpdatedBy User field to Tasks
@todo: add cli logging for operations: <timestamp> <user> <action>
*/