TECHNOLOGY ARCHITECTURE · CTO

Technical maps

The current website's technical map and data read flows: pages, the work API and the data access layer.

Diagrams use Mermaid so technical content can be read, edited and compared with source code. The diagrams below describe the current prototype, not Võ's game backend.

This section explains how technology components connect. To see who receives CEO requests, assigns work and hands over results, read the team coordination process.

CURRENT SYSTEMDiagram version1.0.0

Current system map

Browsers receive pages from Astro. Pages needing fresh data call the server data-access layer; the work API is a separate read path.

Scroll within the frame to explore the full-size diagram. Arrow keys work when the frame is selected.

The diagram renders when it comes into view. You can read all the steps below.

Static pages are generated at build time. SSR pages generate HTML on request; both are read in the browser.
SSR pages call the repository directly. The work API uses the same repository to return JSON; it is not a mandatory intermediary for SSR pages.
Work uses local data. Member profiles combine the member catalog and local activity records and expose only approved public fields.
The prototype has no operational database, public write API, login or payment system yet.

View Mermaid source · v1.0.0

flowchart TB
  accTitle: Current website system map
  accDescr: The browser reads static pages, SSR pages or the work API. SSR pages and the API use repositories to read local data.
  browser["Browser"]
  staticPages["Astro static pages"]
  ssrPages["Astro SSR pages"]
  ticketApi["Work API · GET only"]
  ticketRepo["Work repository"]
  teamRepo["Member repository"]
  ticketData[("Local work data")]
  teamData[("Member catalog and activities")]
  browser -->|"Read page"| staticPages
  browser -->|"Read page"| ssrPages
  browser -->|"Call GET"| ticketApi
  ssrPages --> ticketRepo
  ssrPages --> teamRepo
  ticketApi --> ticketRepo
  ticketRepo --> ticketData
  teamRepo --> teamData

QT0006Process version1.1.0

CURRENT SYSTEMDiagram version1.0.0

Read a work item by ID

GET /api/tickets/{id} distinguishes malformed IDs, nonexistent work items and valid results. The detail page uses the same data layer to render HTML.

Scroll within the frame to explore the full-size diagram. Arrow keys work when the frame is selected.

The diagram renders when it comes into view. You can read all the steps below.

The application sends GET /api/tickets/{id} using the work item's stable ID.
Malformed IDs receive HTTP 400. Valid IDs are looked up through the repository.
If no record is found, the API returns HTTP 404. If a record is found, it returns HTTP 200 with a ticket object containing public fields.
The /tickets/{id}/ route is a separate SSR HTML page: it calls the repository directly and returns a 404 page for an invalid or nonexistent ID.

View Mermaid source · v1.0.0

sequenceDiagram
 accTitle: API reads a work item by ID
 accDescr: The API validates the ID, queries the repository and returns error 400, error 404 or public data 200.
 participant client as Caller
 participant api as Work API
 participant repo as Repository
 client->>api: GET /api/tickets/{id}
 alt Invalid ID format
 api-->>client: 400 · invalid_id
 else Valid ID
 api->>repo: get(id)
 repo-->>api: Record or null
 alt Not found
 api-->>client: 404 · not_found
 else Record found
 api->>api: Select public fields
 api-->>client: 200 · ticket
 end
 end

QT0007Process version1.1.0

CURRENT SYSTEMDiagram version1.0.0

Read a list page by page

GET /api/tickets accepts a project ID, item limit and continuation cursor. Each response contains at most 50 work items.

Scroll within the frame to explore the full-size diagram. Arrow keys work when the frame is selected.

The diagram renders when it comes into view. You can read all the steps below.

The first request has gameId and limit, defaulting to vo and 20. limit must be an integer from 1 to 50.
The repository validates the query. If after is present, that ID must exist in the same project; invalid queries or cursors return HTTP 400.
Results contain public items and nextCursor. A project with a valid ID format but no work returns an empty list.
When nextCursor is not null, send it as after with the same gameId to continue. null marks the end of the current list; response limits do not prove large-scale operating capacity.

View Mermaid source · v1.0.0

sequenceDiagram
  accTitle: Paginated work-list API
  accDescr: The repository checks project, limit and cursor, then returns public items and the next cursor.
  participant client as Caller
  participant api as Work API
  participant repo as Repository
  Note over client,api: gameId=vo, limit=20
  client->>api: GET /api/tickets
  api->>repo: list(gameId, limit, after)
  alt Invalid query or cursor
    repo-->>api: InvalidTicketQuery
    api-->>client: 400 · invalid_query
  else Valid
    repo-->>api: items and nextCursor
    api->>api: Select public fields of each item
    api-->>client: 200 · items and nextCursor
    opt nextCursor is not null
      client->>api: GET with same gameId, after=nextCursor
      api->>repo: Read the next page
      repo-->>api: items and new nextCursor
      api-->>client: 200 · public fields
    end
  end

PROPOSED · NOT IMPLEMENTED

As data and needs grow

The repository provides the contract between the interface and data storage. A next step could replace the local dataset with a database, using indexed ID lookups and source-side pagination. This is an expansion direction; the current prototype has not demonstrated capacity at scale.

Login, authorization, application intake and data writes need separate requirements, design and implementation authority. Current diagrams describe only the public read path.

About team coordination