Workspaces & Projects

Overview

Workspaces and Projects are the core organizational units in AV. Workspaces are multi-tenant containers for collaboration, and Projects are individual ASO (App Store Optimization) tracking initiatives.

Architecture

Workspace (owned by user)
├── WorkspaceUser (membership with roles)
├── Project 1 (ASO Android)
│   ├── AndroidApp
│   ├── Keywords
│   └── ProjectUserAccess (granular permissions)
└── Project 2 (ASO Apple)
    ├── AppleApp
    ├── Keywords
    └── ProjectUserAccess (granular permissions)

---

Workspaces

What is a Workspace?

A Workspace is a multi-tenant container where teams collaborate on app tracking. Each workspace: - Has one owner (the creator) - Can have multiple members with roles (OWNER, ADMIN, VIEWER) - Contains multiple projects for tracking different apps - Provides isolated data (no cross-workspace data sharing)

Workspace Roles

Role	Permissions
OWNER	Full control: create/delete projects, manage members, delete workspace
ADMIN	Create/manage projects, manage workspace members
VIEWER	Read-only access to workspace and shared projects

Creating a Workspace

curl -X POST http://localhost:8000/api/workspaces/ \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Marketing Agency"
  }'

Response (201 Created):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Marketing Agency",
  "owner": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe"
  },
  "members": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "user": {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Doe"
      },
      "role": "OWNER",
      "created_at": "2024-10-28T10:30:00Z",
      "updated_at": "2024-10-28T10:30:00Z"
    }
  ],
  "project_count": 0,
  "created_at": "2024-10-28T10:30:00Z",
  "updated_at": "2024-10-28T10:30:00Z"
}

Listing Workspaces

curl http://localhost:8000/api/workspaces/ \
  -H "Authorization: Bearer $JWT_TOKEN"

Returns all workspaces where you are owner or member.

Adding Members to Workspace

curl -X POST http://localhost:8000/api/workspaces/{workspace_id}/members/ \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_email": "[email protected]",
    "role": "ADMIN"
  }'

Parameters: - user_email (required): Email address of the user to add (user must already be registered) - role (optional): Member role - OWNER, ADMIN, or VIEWER (default: VIEWER)

Only workspace owner or admins can add members.

Removing Members

curl -X DELETE http://localhost:8000/api/workspaces/{workspace_id}/members/{member_id}/ \
  -H "Authorization: Bearer $JWT_TOKEN"

Listing Workspace Members

curl http://localhost:8000/api/workspaces/{workspace_id}/members/ \
  -H "Authorization: Bearer $JWT_TOKEN"

---

Projects

What is a Project?

A Project is an ASO tracking initiative for a specific app. Each project: - Belongs to exactly one workspace - Has a type: ASO_ANDROID or ASO_APPLE - Tracks one app (with keywords, competitors, rankings) - Has granular user permissions (ADMIN, VIEWER)

Project Types

ASO_ANDROID

Tracks Android apps in Google Play Store: - Linked to AndroidApp (package ID) - Keywords in specific country-languages - Competitor tracking - Historical ranking data in ClickHouse

ASO_APPLE

Tracks iOS apps in Apple App Store: - Linked to AppleApp (bundle ID) - Keywords in specific country-languages - Competitor tracking - Fast (1-day) and slow (7-day) metadata caching

Creating a Project

curl -X POST http://localhost:8000/api/workspaces/{workspace_id}/projects/ \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "WhatsApp Tracking",
    "type": "ASO_ANDROID"
  }'

Response (201 Created):

{
  "id": "880e8400-e29b-41d4-a716-446655440004",
  "name": "WhatsApp Tracking",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "ASO_ANDROID",
  "user_access": [],
  "aso_android_config": null,
  "aso_apple_config": null,
  "created_at": "2024-10-28T10:35:00Z",
  "updated_at": "2024-10-28T10:35:00Z"
}

Note

The aso_android_config and aso_apple_config are set to null initially. They get populated when you configure the specific app tracking settings.

Listing Projects

curl http://localhost:8000/api/workspaces/{workspace_id}/projects/ \
  -H "Authorization: Bearer $JWT_TOKEN"

Only returns projects you have access to.

Updating a Project

curl -X PUT http://localhost:8000/api/workspaces/{workspace_id}/projects/{project_id}/ \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "WhatsApp Ranking Tracker"
  }'

Only workspace owner or project admins can update.

Deleting a Project

curl -X DELETE http://localhost:8000/api/workspaces/{workspace_id}/projects/{project_id}/ \
  -H "Authorization: Bearer $JWT_TOKEN"

Only workspace owner or project admins can delete.

---

Project Access Control

Sharing Projects

Workspace owners and project admins can grant project access to other workspace members:

curl -X POST http://localhost:8000/api/workspaces/{workspace_id}/projects/{project_id}/share/ \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_email": "[email protected]",
    "role": "ADMIN"
  }'

Parameters: - user_email (required): Email address of the workspace member to grant access - role (optional): Access level - ADMIN (can edit/share) or VIEWER (read-only) (default: VIEWER)

Note: User must already be a workspace member before receiving project access.

Project Roles

Role	Permissions
ADMIN	Full control: update, delete, share project
VIEWER	Read-only access to project data

Access Rules

1. Workspace owner automatically has access to all projects
2. Other members need explicit ProjectUserAccess entry
3. User must be workspace member before receiving project access
4. No cross-workspace access - can only access projects in workspaces you're a member of

---

Access Control Hierarchy

Request → Is User Authenticated?
  ├─ No → 401 Unauthorized
  └─ Yes → Check Workspace Access
      ├─ Not a member → 403 Forbidden
      └─ Is member → Check Project Access
          ├─ For read → Check ProjectUserAccess | Workspace owner → Allowed
          ├─ For write → Check admin role → Allowed
          └─ Not allowed → 403 Forbidden

---

Example Workflow: Setting Up a Client Workspace

# 1. Create workspace for client
WORKSPACE_ID=$(curl -X POST http://localhost:8000/api/workspaces/ \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Client XYZ"}' | jq -r '.id')

# 2. Add team members
curl -X POST http://localhost:8000/api/workspaces/$WORKSPACE_ID/members/ \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_email": "[email protected]", "role": "ADMIN"}'

# 3. Create Android app tracking project
PROJECT_ANDROID=$(curl -X POST http://localhost:8000/api/workspaces/$WORKSPACE_ID/projects/ \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Main App - Android", "type": "ASO_ANDROID"}' | jq -r '.id')

# 4. Create Apple app tracking project
PROJECT_APPLE=$(curl -X POST http://localhost:8000/api/workspaces/$WORKSPACE_ID/projects/ \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Main App - iOS", "type": "ASO_APPLE"}' | jq -r '.id')

# 5. Share projects with team
curl -X POST http://localhost:8000/api/workspaces/$WORKSPACE_ID/projects/$PROJECT_ANDROID/share/ \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_email": "[email protected]", "role": "VIEWER"}'

---

Common Patterns

Check if you have workspace access

curl http://localhost:8000/api/workspaces/{workspace_id}/ \
  -H "Authorization: Bearer $JWT_TOKEN"
# Returns 200 if you have access, 403 if not

Get all accessible projects in a workspace

curl http://localhost:8000/api/workspaces/{workspace_id}/projects/ \
  -H "Authorization: Bearer $JWT_TOKEN"
# Returns only projects you have access to

Change member role

# Remove old access
curl -X DELETE http://localhost:8000/api/workspaces/{workspace_id}/members/{member_id}/ \
  -H "Authorization: Bearer $JWT_TOKEN"

# Add with new role
curl -X POST http://localhost:8000/api/workspaces/{workspace_id}/members/ \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_email": "[email protected]", "role": "VIEWER"}'

---

Error Handling

Common Status Codes

Code	Meaning	Cause
200	OK	Successful GET request
201	Created	Successful POST request
204	No Content	Successful DELETE
400	Bad Request	Invalid data (e.g., user not workspace member)
401	Unauthorized	Missing or invalid JWT token
403	Forbidden	Don't have permission for this action
404	Not Found	Resource doesn't exist or no access

Example Error Response

{
  "detail": "User is not a workspace member"
}

---

Data Isolation & Multi-Tenancy

All workspace data is strictly isolated:

• ✅ Cannot list workspaces you're not a member of
• ✅ Cannot access projects from other workspaces
• ✅ Cannot add external users directly to projects
• ✅ Member must first join workspace before project access
• ✅ All queries filtered by workspace ownership
• ✅ ClickHouse analytics also workspace-scoped (future)

---

Next Steps

• Authentication - JWT token management
• Data Models - Detailed model specifications
• API Reference - Full API endpoint reference
• ASO Projects - Create and manage ASO projects