Current platform guide

What works today

Concreto is currently a combined static frontend and FastAPI backend. It is useful for demonstrating account management, authenticated dashboard workflows, application source validation, deployment history records, and GitOps handoff commits.

The reliable path today is a Git-backed application: the user provides a GitHub or GitLab HTTPS URL, chooses a site type, and presses Deploy. Deploy creates a deployment record and asks the backend to commit a customer YAML file into the GitOps repo path ArgoCD watches.

Account access

Create an account from Register or sign in from Log in. Authentication is backed by the API, not local demo data.

• Registration and login return a bearer token.
• The frontend stores the token in localStorage as ph_token.
• Authenticated API calls send the token in the Authorization header.
• Logout deletes the stored token and clears the server session when possible.

Create an application

Open the dashboard and click + New application. Each application needs a name, a site type, and a source method.

1. 1
   Open the dashboard

   After signing in, go to Dashboard and open the application form.

2. 2
   Choose a source

   Use Git URL for the working public GitHub/GitLab path. The dashboard also shows Upload ZIP for Laravel and WYSIWYG editor for static sites, but those two paths are not working end-to-end yet.

3. 3
   Create the record

   Concreto validates the source, stores the application record, and shows it in the applications table.

4. 4
   Commit the deployment config

   Click Deploy to create a deployment history entry and commit the customer GitOps YAML when the source has a deployable Git URL.

Site types

• Static sites are served by Nginx from the submitted source. Static sites currently work best from Git. The WYSIWYG option is intended to generate a simple index.html, package it like a ZIP upload, and send it through the same backend validation path once the upload flow is fixed.
• Laravel sites run on the shared Laravel runner image with PHP-FPM, Nginx, and optional MySQL resources from the customer Helm chart. Laravel currently works best from Git. ZIP upload is intended to accept a local Laravel archive, validate it, import it to the customer source repository, and deploy that Git-backed copy once the upload flow is fixed.

Source validation

Source validation happens twice: the browser checks obvious mistakes for fast feedback, and the backend enforces the real rules before anything is stored.

Git URLs

• Only HTTPS URLs on github.com or gitlab.com are accepted.
• GitHub accepts https://github.com/owner/repo; GitLab also accepts subgroups like https://gitlab.com/group/subgroup/repo.git.
• Credentials, query strings, fragments, invalid path characters, and other hosts are rejected.
• Accepted URLs are normalized before they are saved.

ZIP uploads

• ZIP uploads use a real multipart upload endpoint, not a filename-only placeholder.
• The default compressed upload limit is 25 MB.
• The backend rejects invalid ZIP files, empty archives, unsafe paths, symbolic links, source-control metadata, common secret filenames, executable file types, high compression ratios, too many files, and archives that expand past the configured limit.
• ZIP and WYSIWYG are not working end-to-end in the current build, but they are not far off: the intended design already uses the same validation boundary and then imports accepted files into the configured customer source Git repository before ArgoCD deploys them.

Deployments

The Deploy button creates a deployment record for the selected application and asks the backend to commit customers/<customer>.yaml through backend/deploy.py.

• Status values include pending, building, deploying, running, and failed.
• The Deployments view shows the deployment history stored by the backend.
• Successful Git-backed deployments log the GitOps file path, branch, customer namespace, and domain. ZIP/editor deployments should use the same generated YAML shape after their import-to-Git path is fixed.

Metrics

The dashboard includes a Metrics tab. For the current prototype, the frontend renders simulated CPU, memory, and request values for applications that have a running deployment status.

The backend contains Grafana query helpers for future real metrics integration, but the dashboard is not yet wired to display real Prometheus/Grafana data per application.

API endpoints

The implemented API surface is intentionally small and focused on authentication, application records, and deployment records.

POST /api/auth/register
POST /api/auth/login
POST /api/auth/logout
GET  /api/me
GET  /api/applications
POST /api/applications      # Git source JSON
POST /api/applications/zip  # ZIP source multipart upload
GET  /api/deployments
POST /api/deployments
PATCH /api/deployments/{deployment_id}

Current limits

• No public CLI is implemented in this repository.
• The dashboard commits GitOps customer YAML, but it does not run the later ArgoCD sync or Kubernetes rollout itself.
• No custom domain, HTTPS certificate provisioning, webhook, rollback, billing, or quota enforcement flow is implemented in the app UI.
• Git-backed application deployment is the current working source path. ZIP upload and WYSIWYG application creation are close to the intended design but still need follow-up fixes before they can be treated as working paths.
• SQLite is used as the local fallback database. Production should use PostgreSQL through DATABASE_URL.

Operator notes

The production container serves the frontend and backend together on port 8080. Kubernetes manifests live in apps/concreto/k8s/, and ArgoCD should point at that manifest path rather than at arbitrary customer source folders.

When changing application-source behavior, keep apps/concreto/PROJECT_CONTEXT.md updated. Future implementation work should preserve the backend validation contract for Git URLs and ZIP archives.