intent/docs/concept.md

Intent is an app for defining high level feature sets for projects that span one or more implementations.

It's "GitHub for intent". Where tools like GitHub and Forgejo are for tracking the _how_, this tool tracks the _why_. Instead of files of code being the unit of collaboration, it's features. Users can create an issue that describes a problem or new desired functionality, discuss, and then create a new feature or link to an existing feature, with the necessary changes described. The history of the feature is tracked, so the decisions behind why something works the way it does can be known.

This then feeds into the implementations, where one or more repositories of app or package implementations can be linked, and their compliance with the feature set tracked and organized.

Data model:
Organization - higher level wrapper around multiple projects, collaborators
Project - root set of logically-associated problems
Issue - a pre-proposal, bug report, etc that can optionally be linked to an existing Feature, or used to create a new Feature (promoted to a Feature(status=active)), or not associated with any Feature, (status=open, rejected, accepted), a potential change to a feature
Feature - a free markdown description of a particular functional solution to a problem within a Project, with discussion (comments can be resolved, or converted to Issues), associated Issues, prototype files, documentation files, and associated Implementation status. Can have parent Features to create a hierarchy of any depth (and have independent statuses for V1). Have a stable ID to be referenced by Implementation changes and Issues, and a status. They also have a sequential revision number that Implementations can reference to catch up with the latest version of the Feature. (status=active, withdrawn, superseded)
Implementation - name and status (active, archived), a repository in any forgejo instance, one or more can be linked to the project and represent a particular implementation of the project, they have features associated, not necessarily all features (marked N/A for that implementation). Intent itself only links to a repo host elsewhere, it does not need to store the repo itself. It can provide links to implementation releases (V1.1). Each Implementation can be on a different Forgejo instance (assume the Forgejo already has the Intent instance onboarded once we get to V1.1, to start it's purely a URL to click on). Per feature × implementation status is one of: n/a, not started, in progress, shipped, retired, stamped with the feature revision number it applies to so it's clear if an Implementation has fallen behind.
CommentThread - hangs off specific lines in the Feature description, the general feature, a whole file, a specific coordinate of an image file, an Issue. Can be resolved (to collapse and hide)
User - basic user account, optionally linked to Organization as Team Member
Comment - a specific versioned comment from a User that's part of a CommentThread

Feature history is like git history, each edit is a commit with notes explaining the change. They are edited directly by team members (as if commiting directly to main) - and edits can be tied to an Issue. To start, Implementation status is purely manual. The Intent data lives entirely within its own data store.

For V1.1: after making changes to a feature, the user can optionally create issues back on the forgejo instance to do the implementation (optionally passing agent-specific instructions on top of links back to the Intent content). (Flow is mostly one-way, Intent -> Forgejo, but delivery status does propagate back to Intent via commit messages. Issues on Forgejo do not propagate back to Intent.)

Users can authenticate using Forgejo, GitHub, Discord, or email (magic link) (and multiple of these by linking their auths together). System admin users can use password authentication (these users are separate from regular users and cannot act within projects).


Tenancy: multiple organizations and teams, potentially many public users
(just a few organizations to start and only a handful of projects and colalborators, at most dozens of users overall)

Users of the Intent app DO NOT need accounts with the underlying Forgejo instances. (V1.1: only users with Forgejo access can set up the syncing with the target repositories etc, via a Forgejo service user + scoped token stored per org. All users can see the Implementation status, but the visibility of the Forgejo project's details propagates to Intent.) In V1 an Implementation is just a URL and Intent never calls the Forgejo API.

Not needed for V1: notifications, search, public API or MCP, Forgejo issue creation, release links

Organization and user structure imitates forgejo (does not sync data but a user linking a repo from forgejo requires an account on both, such as a service-user):
- Organization (can only be created by sysadmin for V1, requires specifying an owner User who can add additional team members, only owner-role can manage team members though they need to accept invite and can remove themselves)
  - team members (Users who are either collaborators or owners of the org): one set of team members per org
  - Project
    - any team member with the org-level project-create grant (set by org owners) can create a project and becomes its owner
    - team member can have project-owner permissions (admin actions like delete project, manage project members) and/or collaborator actions (accept issues, create and update features, create/link implementations and update statuses). Collaborator access is granted per project.
    - org owners can add themselves to any org project as collaborators, and admin the project
    - can allow open contribution from other non-team Users (Issue creation, comments) or restrict these to team members only
    - may be completely private and only visible to project members (plus org owners), require auth so only logged-in users can see, or fully public so the world can see and browse (but only logged-in users can contribute/comment)
- Users
  - can freely contribute to projects that allow open contributions (depending on those permissions) including comment on features and promote those comment threads to an Issue (original commenter or team member can do this, other users cannot)
  - cannot create projects outside of an organization

Front-end approach: Django + HTMX + Alpine to start with islands of rich interactivity where needed.
Styling: extremely minimal. Largely browser defaults; if the stylesheet failed to load the look-and-feel should not be drastically different (layout aside). Accessibility is key. Dark mode from the start.
Back-end: Django, Sqlite (Litestream), deployed onto Fly.io and using Tigris object store. Database backups to B2
Local development: Docker (Fly uses Docker also)
Transactional email (magic links, invites): provider TBD. Console backend in development.

Already have credentials for Fly and B2.

See plan.md for the V1 implementation plan and the defaults chosen for details not covered here.



For example:

1. A general User creates a new Issue in a Project.
2. Multiple Users including team members discuss in comments on the Issue.
3. A Team Member decides to accept the Issue, which closes it to status=accepted, and the creates a new Feature and writes the description of it (the Feature is linked to the Issue it came from)
4. The Team Member then updates the status of the Feature manually to track with implementations
5. Later, a User starts a comment thread on a Feature.
6. After some Discussion, the User promotes the thread to an Issue.
7. More discussion, then a Team Member accepts the Issue and updates the Feature (manually for V1)
      - or, a Team Member rejects the Issue and it's marked as rejected, but still linked to the Feature so others can see it was put forward and rejected