mxpic_EDA/develop_plan/findings.md

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.