Update architecture docs to match the codebase#2856
Merged
michaeldwan merged 7 commits intomainfrom Mar 23, 2026
Merged
Conversation
…untime The legacy Python/FastAPI runtime has been removed and coglet is the only runtime. This updates the architecture docs to reflect that: - Delete architecture/legacy/ and architecture/ffi/ subdirectories - Create canonical 03-prediction-api.md and 04-container-runtime.md - Fix false claim that wheels are embedded in the Go binary - Fix pydantic claims (schema gen uses inspect + custom ADT dataclasses) - Fix stale file references (base_predictor.py, pkg/api/, etc.) - Mark static schema path as experimental - Fix compatibility matrix filenames, Swagger UI ghost, cog.BaseModel name
Add skills/updating-architecture-docs/ to capture the intent and process for maintaining architecture docs -- bridge from concepts to code, not code summaries. Apply the skill's principles to 03-prediction-api.md and 04-container-runtime.md: cut obvious Rust snippets that just restate code (status lifecycle, idempotent PUT, error handling), keep non-obvious ones that convey meaning prose can't (RAII guard, permit model). Replace exhaustive file listings and code reference tables with package-level pointers. Slim down component ownership tree to conceptual description.
…t missing features Fix health state machine to start at UNKNOWN (not STARTING), add UNHEALTHY state for user-defined healthchecks. Complete IPC protocol tables with all message variants (~8 were missing). Document four previously undocumented features: input spilling, file outputs, custom metrics, user-defined healthchecks. Expand env var table and Go package listing. Add hidden CLI commands. Fix crates/README.md duplicate line. Update skill to prefer important packages over exhaustive listings.
michaeldwan
changed the title
michaeldwan
changed the title
…sections Addresses the question 'what is the lifetime of BasePredictor and what can I do with it at each stage?' -- previously undocumented. - Predictor Lifecycle in 04: singleton instance, setup() once, self persists, no teardown, concurrency semantics, crash is terminal (no respawn) - Life of a Prediction in 04: 9-step request-to-response walkthrough with error handling - Cross-references from 01 setup()/predict() sections - Fixes pre-existing incorrect DEFUNCT health claim in Why Two Processes
The SDK was in the diagram but disconnected and missing from the Components section and terminology table. Now it's a first-class entry so people can distinguish 'the CLI' from 'the SDK' from 'coglet'.
markphelps
approved these changes
Mar 23, 2026
Contributor
markphelps
left a comment
markphelps
left a comment
There was a problem hiding this comment.
nice skill, although will it work if its not in the bespoke locations? like .claude or .agents or whatever?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The architecture docs were written before the legacy Python runtime was removed and coglet became the sole runtime. They described a system that no longer exists.
This updates them to reflect reality and adds a skill for keeping them accurate as the code evolves.