Adding onboarding doc with excalidraw images

[maernest04]

PR for #150

Problem

For SCEvents, we have the original development team but we need to add more contributors to help maintain the project as time goes on. Currently, there is no onboarding documentation for SCEvents, making it difficult to add more people.

Solution

Added an onboarding document covering:

• Project architecture and dependencies
• Local setup and testing
• Domain concepts and registration flow
• API and Clark integration
• Debugging and recovery guidance
• Development and deployment workflows

[steeevin88]

nice addition + definitely helps with ramping up onto SCEvents

only potential gripe I have is updating this doc once the project changes/ new features are added; how can we prevent this some getting stale?

ex. we initially avoided super verbose code pointers in the READ.ME b/c we (rightly) anticipated code changes

ideally updating this doc is just automated but idk what budget would be needed, what do you think

[maernest04]

I think it's a pretty big problem we'll have to deal with that. Automation is a possibility as we could schedule codex or claude code to review merged PRs each week, make changes to relevant docs so the readme or onboarding docs, and open a PR with these updated docs.

Another thing we can do is more of a subconscious rule of any user being onboarded that when they add a new feature and PR, they should always double check if their edits call for documentation changes. Obviously this is less reliable so it's more of a pick your poison atp.

[steeevin88]

I think it's a pretty big problem we'll have to deal with that. Automation is a possibility as we could schedule codex or claude code to review merged PRs each week, make changes to relevant docs so the readme or onboarding docs, and open a PR with these updated docs.

Another thing we can do is more of a subconscious rule of any user being onboarded that when they add a new feature and PR, they should always double check if their edits call for documentation changes. Obviously this is less reliable so it's more of a pick your poison atp.

would it maybe make more sense for this documentation to just live elsewhere? maybe just being nitpicky but especially with automation the repo would get flooded with doc update PRs that aren't really relevant

[maernest04]

I think it's a pretty big problem we'll have to deal with that. Automation is a possibility as we could schedule codex or claude code to review merged PRs each week, make changes to relevant docs so the readme or onboarding docs, and open a PR with these updated docs.
Another thing we can do is more of a subconscious rule of any user being onboarded that when they add a new feature and PR, they should always double check if their edits call for documentation changes. Obviously this is less reliable so it's more of a pick your poison atp.

would it maybe make more sense for this documentation to just live elsewhere? maybe just being nitpicky but especially with automation the repo would get flooded with doc update PRs that aren't really relevant

This is pretty valid. For the automation part we don't necessarily have to have codex or claude make a PR, we can just have it review the merges and give us a summary of doc changes we should make on a weekly basis. This way we can still maintain the automation idea but we can maintain the documentation manually.