# Project Findings

## Repository Inventory
- Static/frontend files are under `frontend/`: `login.html`, `dashboard.html`, `canvas.html`, and `canvas-helpers.js`.
- Backend files are under `backend/`: `server.py`, `database.py`, `pdk_access.py`, `technology_manifest.py`, `gds_builder.py`, routing helpers, icons, and `directories.yaml`.
- Persistent data appears under `database/`, including `mxpic_data.db`, saved layout YAML/SVG files, and generated `_exports/*.gds`.
- Tests are JavaScript static/unit-style tests under `tests/`.
- Project docs exist under `docs/`, including intranet deployment, GDS/SVG generation, and PDK technology loading notes.
- A checked saved layout example at `database/engineer/layout/mxpic_project_1/mxpic_project_1.yml` contains unresolved merge-conflict markers, so at least some local saved data may be invalid until cleaned.
- Conflict-marker search also found real markers in `database/engineer/layout/mxpic_project_1/mxpic_project_1.svg`, `tests/layout-ui-wiring.test.js`, and `tests/layout-backend-static.test.js`.
- `backend/directories.yaml` is a legacy/declarative directory category file with PDK-style categories; the active docs/source show library scanning is now driven by the role-scoped PDK filesystem.

## Saved Layout YAML Shape
- Saved layout YAML uses schema version `2.0.0`, `kind: cell`, `coordinate_system: gds_y_up`, `canvas_size`, `project`, `name`, `type`, and `version`.
- Modern YAML uses `pins`, `instances`, `elements`, and `bundles`.
- `instances` can reference basic components like `circle`, generated/forge components, other project cells, or PDK paths such as `Silterra/<technology>/primitives/...`.
- `bundles.output_bus.links` stores routed connections with source/target pins and route settings.
- Both checked `.project.json` metadata files (`admin` and `engineer`) select technology `Silterra/EMO1_2ML_CU_Al_RDL`.

## README / Deployment
- The project is `mxpic_EDA`, an EDA layout tool for OptiHK.
- Runtime requirement explicitly listed in README is Flask.
- The application can launch login, dashboard, canvas editing, YAML generation, and PDK browsing without build-time router dependencies.
- Build/export actions require `mxpic_router` and Nazca; if `mxpic_forge.Route` is unavailable, routing falls back to Nazca interconnects.
- SVG preview generation for routed/build output requires `gdstk`.
- Intranet server is started with `run_intranet_server.ps1` and listens on `0.0.0.0:3000` by default.
- LAN users browse to `http://<host-computer-ip>:3000`; firewall must allow inbound TCP `3000`.
- Default local accounts are `admin / 123456` and `engineer / 123456`.
- User project files are stored under `database/<username>/layout`.
- Important env vars include `MXPIC_SECRET_KEY`, `MXPIC_HOST`, `MXPIC_PORT`, `MXPIC_DEBUG`, `MXPIC_COOKIE_SECURE`, `MXPIC_PDK_PUBLIC_ROOT`, and `MXPIC_PDK_ATLAS_ROOT`.
- Public/developer PDK roots default to `../opt_pdk_public/foundries`; manager/atlas roots default to `../opt_pdk_atlas/foundries`.
- `run_intranet_server.ps1` sets default `MXPIC_SECRET_KEY` if absent, sets `MXPIC_HOST=0.0.0.0`, `MXPIC_PORT=3000`, `MXPIC_DEBUG=0`, then runs `python backend\server.py`.
- `backend/server.py` initializes the local SQLite database when the server process starts.
- Flask runs threaded on the configured host and port.

## GDS / SVG Generation
- `Build Layout` serializes the active canvas page into layout YAML, posts it to `/api/save-layout`, writes `database/<username>/layout/<project>/<cell>.yml`, writes optional route sidecar data, then calls router-backed SVG preview generation.
- Routed SVG preview uses `backend/routed_layout_preview.py`, which delegates to `mxpic_router.build_project_gds`, reads the temporary GDS with `gdstk`, and writes `<cell>.svg`.
- `Build GDS` posts to `/api/build-gds` with only the project name. It does not automatically serialize unsaved in-memory canvas state first.
- Final GDS export reads existing saved project YAML files, calls `backend/gds_builder.py`, delegates to `mxpic_router`, writes `database/_exports/<uuid>/<project>.gds`, returns a download URL, then cleans up the export folder after response close.
- Saved layout files are under `database/<username>/layout/<project>/`.
- External build dependencies are lazy: normal web usage can work without router stack, while preview/build actions require `mxpic_router`, Nazca, and sometimes `gdstk`.

## PDK / Technology / Xsections
- PDK components, technology manifests, and GDS assets all come from role-scoped PDK roots.
- Dashboard loads available technologies from `/api/technologies`, scanning `<active_role_pdk_root>/<foundry>/<technology>/technology.yml`.
- Project creation stores selected technology in `database/<username>/layout/<project>/.project.json`.
- Canvas loads project metadata from `/api/projects/<project>`, then loads `/api/technologies/<foundry>/<technology>/manifest`.
- `technology.yml` supplies layer mappings, routing type options, defaults, and xsection definitions such as `strip`, `rib_low`, `metal_1`, and `metal_2`.
- Canvas route editing uses the active technology manifest to populate xsection choices and route defaults.
- Saved YAML stores component paths and per-link route data such as `xsection`, `family`, `width`, `radius`, and `routing_type`.
- Build-time router applies `technology.yml` to Nazca layers/xsections before resolving PDK assets and routing links.

## Backend Route Surface
- `backend/server.py` serves `/`, `/dashboard`, `/canvas`, `/canvas-helpers.js`, and `/logout`.
- Login endpoint is `POST /login`.
- Health check endpoint is `/api/health`.
- Account/profile endpoints include `/api/profile`, `/api/profile/password`, and `/api/logs`.
- Project endpoints include listing/creating `/api/projects`, reading/deleting `/api/projects/<project_name>`, cell rename/delete under `/api/projects/<project_name>/cells/<cell_name>`, and `/api/save-layout`.
- Build/export endpoints include `/api/build-gds`, `/api/exports/<export_id>/<filename>`, and `/api/projects/<project_name>/gds/<filename>`.
- PDK/technology endpoints include `/api/technologies`, `/api/technologies/<foundry>/<technology>/manifest`, `/api/library`, `/api/component/<component_name>`, `/api/component/<component_name>/image`, and `/api/icon/<category>`.
- Project listing treats each `.yml`/`.yaml` inside a project folder as one saved cell/canvas.
- Project creation sanitizes the requested name, adds a numeric suffix if needed, creates an initial project folder, writes `.project.json`, and logs `project.create`.
- `/api/save-layout` accepts `project`, `cell`, `content`, and optional `preview` flag.
- `/api/library` rebuilds the component tree on each request so project technology and user role are reflected immediately.

## Frontend Page Flow
- `frontend/login.html` renders a login form that submits `POST /login` and then moves authenticated users into the dashboard.
- `frontend/dashboard.html` loads recent logs from `/api/logs`, profile data from `/api/profile`, projects from `/api/projects`, and technology choices from `/api/technologies`.
- Opening a project navigates to `/canvas?project=<name>`.
- Creating a project posts `{ name, technology }` to `/api/projects`.
- Dashboard also supports deleting projects, updating occupation, and changing password through backend APIs.
- `frontend/canvas.html` loads project metadata/cells from `/api/projects/<project>`, then loads the selected technology manifest.
- Canvas loads the component library with `/api/library?project=<project>`, component metadata from `/api/component/<component_name>?project=<project>`, and component images from `/api/component/<component_name>/image?project=<project>`.
- Canvas save/build controls call `/api/save-layout` and `/api/build-gds`.
- Dashboard `openProject(name)` navigates directly to `/canvas?project=<name>`.
- Canvas `loadTechnologyManifest` falls back to `FALLBACK_TECHNOLOGY_MANIFEST` when the saved technology is missing/invalid.
- Canvas `fetchLibrary` is project-scoped, so the visible library follows the selected project technology.
- Canvas source comments define the control split:
  - `handleBuildLayout`: save active page, generate preview assets, show preview tab.
  - `handleSaveProjectLayouts`: save YAML for every editable page without opening previews.
  - `handleBuildGds`: build project GDS through the backend and trigger download.

## Database
- `backend/database.py` uses SQLite at `database/mxpic_data.db`.
- Tables: `users` and `user_logs`.
- User records include password hash, creation date, credits, occupation, and `user_group`.
- Database migrations add missing columns to older local SQLite files.
- Default account roles are `admin -> manager`, `engineer -> developers`, and ordinary users default to `user`.
- Audit logs record user action, project/cell context, detail, IP address, and UTC timestamp.

## PDK Access and Build Helpers
- `backend/pdk_access.py` defines supported user groups: `manager`, `developers`, and `user`.
- Managers resolve to `MXPIC_PDK_ATLAS_ROOT` or `opt_pdk_atlas/foundries`; developers/users resolve to `MXPIC_PDK_PUBLIC_ROOT` or `opt_pdk_public/foundries`.
- Only managers prefer full component GDS assets; other roles use public/black-box style assets.
- Temporary GDS exports are created in UUID folders and old export folders are cleaned up after an age threshold.
- `backend/gds_builder.py` validates that saved cell YAML files exist, then delegates all final GDS work to `mxpic_router.build_project_gds`.
- Local GDS building is not implemented as a fallback in this repository.

## Tests
- Tests are JavaScript assertion scripts in `tests/`.
- The test suite heavily checks static frontend/backend integration contracts, such as route existence, API strings, layout/GDS wiring, technology manifest loading, and PDK access behavior.
- `tests/canvas-helpers.test.js` directly imports `frontend/canvas-helpers.js` and checks handle placement, YAML serialization, route defaults, element ports, route YAML, and route crossing helpers.
- Several tests intentionally assert that legacy local preview/registry modules are absent and that the router-backed preview/GDS path is present.
- Current checked test files include unresolved conflict markers in at least two files, so `node` test execution may fail before assertions run unless those files are cleaned.

## Open Questions
- None remaining for the requested project usage/workflow summary.