document user stories for web portal

docs/modules/ROOT/nav.adoc

@@ -1,2 +1,5 @@
 * xref:index.adoc[Home]
-* xref:terminology.adoc[]
+* xref:terminology.adoc[]
+
+* Web Portal
+** xref:user-stories.adoc[]

docs/modules/ROOT/pages/index.adoc

@@ -1,3 +1,7 @@
-= Servala
+= Servala - Open Cloud Native Service Hub
 
-Hello World
+image::servala.png[]
+
+Welcome to https://servala.com/[Servala - Open Cloud Native Service Hub^].
+
+This site documents the technical aspect of Servala.

docs/modules/ROOT/pages/user-stories.adoc

@@ -0,0 +1,171 @@
+= User Stories
+
+== End User Stories
+
+The end user is a person using the portal to discover and order managed services on behalf of an organization,
+manage service instances on multiple managed service providers and do administrative stuff like updating user details.
+
+=== Authentication & Access
+
+As a user, I want to:
+
+MVP::
+* P1: log in using my VSHN Account via OpenID Connect so that I can access the portal securely
+* P1: be automatically registered in the portal when I first log in with my VSHN Account so that I can start using the portal immediately
+* P1: see which organizations I'm a member of so that I can switch between different organization contexts
+* P1: be guided to the VSHN Account portal to update my account details like the password or two-factor authentication
+
+Next::
+* accept organization invitations so that I can join new organizations
+* see my role and permissions within each organization so that I understand my access levels
+
+=== Service Discovery & Management
+
+As a user, I want to:
+
+MVP::
+* P1: see service plans filtered based on my organization's context so that I only see relevant offerings
+* P1: order new service instances by selecting plans, and configuring parameters so that I can provision instances
+* P1: view my existing service instances across all control planes so that I can manage my service instances
+* P1: access connection credentials for my service instances so that I can use the services
+* P1: update parameters of existing service instances so that I can adjust instances as needed
+* P1: delete service instances when they're no longer needed so that I don't incur unnecessary costs
+* P1: receive clear error messages and warnings when operations fail so that I can take appropriate action
+* P2: see the status and health of my service instances so that I can monitor their operation
+* P2: browse the service catalog without authentication so that I can explore available services before committing
+* P2: view detailed service descriptions, pricing, and features so that I can make informed decisions
+
+Next::
+* access service metrics in a pre-configured dashboard-like view with timerange selection
+* access service logs, search for terms in the logs and select a timerange
+* list available backups and select one to restore from
+* restart a service instance
+* clone a service instance
+* manage access control to a service instance
+* see service usage for cost-control
+* upgrade a service instance (plan, software version)
+* configure backup details (time, retention)
+* configure maintenance policies
+* configure pre-defined alert rules and add custom alert destinations
+
+== Organization Admin Stories
+
+An organization admin does administrative tasks like managing access control in the organization, downloads invoices or updates billing details.
+
+=== Organization Management
+
+As an organization admin, I want to:
+
+MVP::
+* P1: manage user access to my organization so that I can control who has access to resources
+* P2: view and manage the organization's billing entity so that I can handle financial aspects
+
+Next::
+* assign different roles to users within my organization so that I can delegate responsibilities appropriately
+* send invitations to new users so that they can join the organization
+* administer billing details
+* list invoices, see their status and download them as PDF
+* directly pay invoices with online billing
+
+== Managed Service Provider Stories
+
+A managed service provider manages their content and service instances.
+
+=== Content Management
+
+As a managed service provider, I want to:
+
+Next::
+* manage my service offering
+* manage plans and pricing
+* update my company details
+
+=== Instance Management
+
+As a managed service provider, I want to:
+
+Next::
+* see all instances running on my infrastructure
+* get access to customer information for customers running instances on my infrastructure
+* see service instance usage details for billing purposes
+
+== Portal Admin Stories
+
+The portal admin is the "root" of the system and does backend administrative tasks.
+It also includes managing the content.
+
+=== System Configuration
+
+As a portal admin, I want to:
+
+MVP::
+* P1: register and manage control planes so that they're available for service deployment
+* P1: configure system-level service account credentials so that the portal can interact with control planes
+* P1: configure organization origins and their associated rules so that I can control service provider access
+* P2: customize field names and form behaviors so that the user interface is intuitive
+
+Next::
+* access audit logs to see what's going on in the portal
+
+=== Content Management
+
+As a portal admin, I want to:
+
+MVP::
+* P1: manage service providers and their metadata so that users can discover available services
+* P1: manage the service catalog including categories and hierarchies so that services are well-organized
+* P2; configure service plans and pricing so that offerings are current
+* P2: manage service metadata including logos and external links so that service information is complete
+
+Next::
+* manage the public website content so that I can keep service information up to date
+
+== System Stories
+
+This is the system itself doing administrative tasks.
+
+=== Service Discovery & Sync
+
+As the system, I want to:
+
+MVP::
+* P1: automatically discover service definitions (Crossplane XRDs) from control planes so that available services are current
+* P1: sync organization data with the APPUiO Control API so that organization information stays consistent
+* P2: validate service instance operations against control plane APIs so that only valid configurations are accepted
+
+Next::
+* regularly update OpenAPI specs from control planes so that service parameters are current
+
+=== Authentication & Authorization
+
+As the system, I want to:
+
+MVP::
+* P1: enforce organization context for all operations so that multi-tenancy is maintained
+* P1: create organization namespaces in control planes on first use so that service instances can be deployed
+* P2: handle OIDC token exchange for user operations on control planes so that actions are properly authenticated
+
+Next::
+* validate user permissions against roles so that access control is maintained
+
+=== Error Handling & Monitoring
+
+As the system, I want to:
+
+MVP::
+* P1: gracefully handle upstream API failures so that the application remains stable
+* P1: provide appropriate error messages for failed operations so that users understand issues
+* P1: track failed operations and sync attempts so that issues can be investigated
+* P2: monitor control plane connectivity so that service availability can be maintained
+
+== API Consumer Stories
+
+=== API Integration
+
+As an API consumer, I want to:
+
+Next::
+* authenticate with the portal API so that I can access resources programmatically
+* manage service instances via REST API so that I can automate infrastructure provisioning
+* retrieve service catalog information via API so that I can display available services
+* manage organization instances via API so that I can integrate with other systems