diff --git a/docs/modules/ROOT/assets/images/servala.png b/docs/modules/ROOT/assets/images/servala.png new file mode 100644 index 0000000..af5de89 Binary files /dev/null and b/docs/modules/ROOT/assets/images/servala.png differ diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index fc6dcf2..2b92062 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,2 +1,5 @@ * xref:index.adoc[Home] -* xref:terminology.adoc[] \ No newline at end of file +* xref:terminology.adoc[] + +* Web Portal +** xref:user-stories.adoc[] \ No newline at end of file diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 50e418f..7a41ca9 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/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. diff --git a/docs/modules/ROOT/pages/user-stories.adoc b/docs/modules/ROOT/pages/user-stories.adoc new file mode 100644 index 0000000..c5dcc13 --- /dev/null +++ b/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